@lh8ppl/claude-memory-kit 0.3.5 → 0.4.1

package/src/subcommands.mjs

@@ -14,6 +14,16 @@
 // asserts exactly what's exported here, so coverage stays automatic.
 
 import { install as installAction, initUserTier as initUserTierAction } from './install.mjs';
+import { installAgent } from './install-agent.mjs';
+import { installKiro, uninstallKiro } from './install-kiro.mjs';
+import { getAgentProfile, listAgentProfiles } from './agent-profiles.mjs';
+import { runKiroHook } from './kiro-hook-bin.mjs';
+import { readKiroTurn } from './kiro-transcript.mjs';
+import { injectContext } from './inject-context.mjs';
+import { captureTurn } from './capture-turn.mjs';
+import { capturePrompt } from './capture-prompt.mjs';
+import { observeEdit } from './observe-edit.mjs';
+import { decideGuard } from './guard-memory.mjs';
 import { removeClaudeMdBlock } from './claude-md.mjs';
 import { reindex as reindexAction } from './reindex.mjs';
 import { openIndexDb } from './index-db.mjs';
@@ -52,7 +62,7 @@ import {
 } from './register-crons.mjs';
 import { fileURLToPath } from 'node:url';
 import { dirname } from 'node:path';
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 
 const __filename_subcommands = fileURLToPath(import.meta.url);
 const __dirname_subcommands = dirname(__filename_subcommands);
@@ -65,6 +75,27 @@ import { createInterface } from 'node:readline';
 import { spawnSync } from 'node:child_process';
 import { checkKitBinding } from './native-binding.mjs';
 import { resolve as resolvePath, join, basename } from 'node:path';
+import { resolveMcpProjectRoot, normalizeProjectPath } from './tier-paths.mjs';
+
+/**
+ * Resolve the cmk-auto-extract.mjs bin path so the KIRO stop hook's captureTurn
+ * can spawn the detached auto-extract child (D-200). Mirrors the Claude Code bin's
+ * resolution (env override → sibling bin/): without this, runHook called
+ * captureTurn with no autoExtractPath and the in-module default is null, so
+ * spawnAutoExtract short-circuits 'no-auto-extract-path' — capture writes the
+ * transcript but NEVER extracts facts → no wedge promotion. The CLI's runHook
+ * lives in src/, so the bin is a `../bin/` sibling. A missing bin → null → no
+ * spawn (fail-safe for a never-crash hook); spawnAutoExtract logs the reason.
+ * @param {Record<string,string|undefined>} [env=process.env]
+ * @returns {string|null} absolute path to the bin, or null if it can't be found
+ */
+export function resolveKiroAutoExtractPath(env = process.env) {
+  if (env.CMK_AUTO_EXTRACT_PATH && env.CMK_AUTO_EXTRACT_PATH.trim() !== '') {
+    return env.CMK_AUTO_EXTRACT_PATH;
+  }
+  const sibling = join(__dirname_subcommands, '..', 'bin', 'cmk-auto-extract.mjs');
+  return existsSync(sibling) ? sibling : null;
+}
 
 const NOTICE_PREFIX = 'not yet implemented';
 
@@ -169,6 +200,16 @@ export async function runInstall(options /* , command */) {
   // commander maps `--no-hooks` to options.hooks === false.
   const noHooks = !!(options && options.hooks === false);
   const verbose = !!(options && options.verbose);
+
+  // Task 50.F — cross-agent routing. Default is claude-code (the existing path,
+  // untouched). For another agent, scaffold the agent-neutral project tier via
+  // installAction with hooks OFF (the Claude-Code hook wiring doesn't apply), then
+  // wire THAT agent's legs (hooks + MCP + instruction file) via installAgent.
+  const ide = (options && options.ide) || 'claude-code';
+  if (ide !== 'claude-code') {
+    return runInstallForAgent({ ide, options, log, logError });
+  }
+
   const result = await installAction({
     force: !!(options && options.force),
     noHooks,
@@ -254,20 +295,281 @@ export async function runInstall(options /* , command */) {
 }
 
 /**
- * `cmk uninstall` — wired in Task 4. Strips the kit-managed block from
- * the project's CLAUDE.md (if present). Everything outside the markers
- * is byte-preserved. Does NOT touch context/, context.local/, the user
- * tier, or .gitignore — `cmk uninstall` is conservative; users delete
- * those by hand if they really want to.
+ * Task 50.F — `cmk install --ide <agent>` for a non-Claude-Code agent.
+ * Scaffolds the agent-neutral project tier (context/, CLAUDE.md block, gitignore —
+ * via installAction with hooks off, since the Claude-Code hook wiring doesn't
+ * apply), then wires THAT agent's legs (hooks + MCP + instruction file) via
+ * installAgent. One step — no second command (the user-friendly criterion).
  */
-function runUninstall(/* options, command */) {
-  const projectRoot = resolvePath(process.cwd());
+async function runInstallForAgent({ ide, options, log, logError }) {
+  const profile = getAgentProfile(ide);
+  if (!profile) {
+    const known = listAgentProfiles().map((p) => p.name).join(', ');
+    logError(`cmk install: unknown --ide '${ide}'. Supported: ${known}.`);
+    process.exitCode = 2;
+    return;
+  }
+
+  // 1) agent-neutral scaffold (context/ + the kit's own CLAUDE.md block live
+  //    regardless of agent). Hooks OFF — the agent's hooks are wired in step 2.
+  //    skipClaudeFiles: `.claude/skills/` + `CLAUDE.md` are Claude-Code-specific;
+  //    a non-CC agent gets its instructions from its own surface (Kiro →
+  //    .kiro/skills/ + .kiro/steering/ + AGENTS.md), so we must not leave dead
+  //    Claude files on the project (D-188). An EXISTING Claude install's files
+  //    are untouched — we just don't create fresh ones.
+  const scaffold = await installAction({
+    force: !!(options && options.force),
+    noHooks: true,
+    withSemantic: !!(options && options.withSemantic),
+    noSemantic: !!(options && options.semantic === false),
+    projectRoot: options?.cwd,
+    userTier: options?.userTier,
+    bindingProbe: options?.bindingProbe,
+    spawnNpm: options?.spawnNpm,
+    warmEmbedder: options?.warmEmbedder,
+    skipClaudeFiles: true,
+  });
+
+  const projectName = basename(scaffold.projectRoot);
+
+  // 2) wire the agent's surfaces. Kiro has its OWN orchestrator (D-182): five
+  //    surfaces (MCP + steering + skills + IDE hooks + the CLI agent-config),
+  //    not the generic installAgent's Claude-Code-shaped model.
+  if (ide === 'kiro') {
+    // awsDir: tests/sandboxes pass $MEMORY_KIT_AWS_DIR via options.awsDir to keep
+    // the CLI-agent leg out of the real ~/.aws; production leaves it undefined →
+    // the real ~/.kiro (where kiro-cli actually reads its agents).
+    const r = installKiro({ projectRoot: scaffold.projectRoot, awsDir: options?.awsDir });
+    if (r.action === 'error') {
+      for (const e of r.errors || []) {
+        logError(`  error: Kiro ${e.surface}: ${(e.errors || []).join('; ')}`);
+      }
+      logError(
+        `cmk install: ${projectName} scaffolded but Kiro wiring failed (a config file could not be safely written — see above).`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+    log(
+      `cmk install: ${projectName} ready for Kiro — context/ scaffolded; ${r.surfaces.join(' + ')} wired.`,
+    );
+    log('  Restart Kiro to activate the hooks (steering + skills + MCP are immediate).');
+    // The CLI agent-config (kiro-cli) is automatic only when cmk is the default
+    // agent. If the user already has a default, surface the one manual step.
+    if (r.cliDefaultAgent === 'skipped-existing') {
+      log('  Note: you already have a Kiro CLI default agent — the kit installed a `cmk` agent instead.');
+      log('        Run `kiro-cli --agent cmk`, or set `chat.defaultAgent` to `cmk`, for automatic CLI memory.');
+    }
+    if (scaffold.errors.length > 0) {
+      for (const e of scaffold.errors) logError(`  error: ${e.path}: ${e.error}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  // Other agents: the generic per-profile installer.
+  const wired = installAgent({ projectRoot: scaffold.projectRoot, profile });
+
+  if (wired.action === 'error') {
+    for (const e of wired.errors || []) {
+      logError(`  error: ${profile.displayName} ${e.leg}: ${(e.errors || []).join('; ')}`);
+    }
+    // Report which legs DID land (every leg is independently idempotent +
+    // touch-only, so a re-run after fixing the flagged file is safe).
+    const landed = Object.entries(wired.legs || {})
+      .filter(([, action]) => action && action !== 'error')
+      .map(([leg]) => leg);
+    if (landed.length) {
+      logError(`  (${landed.join(' + ')} already wired; re-run after fixing the file above — safe, idempotent.)`);
+    }
+    logError(
+      `cmk install: ${projectName} scaffolded but ${profile.displayName} wiring failed (a config file could not be safely written — see above).`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  // Describe what THIS integration type actually wired (instruction-only writes
+  // just the instruction file; full agents wire hooks + MCP too).
+  const wiredLegs = [
+    wired.legs.instruction ? 'instruction file' : null,
+    wired.legs.mcp ? 'MCP' : null,
+    wired.legs.hooks ? 'hooks' : null,
+  ].filter(Boolean);
+  log(
+    `cmk install: ${projectName} ready for ${profile.displayName} — context/ scaffolded, ${wiredLegs.join(' + ')} wired.`,
+  );
+  if (profile.integrationType === 'instruction-only') {
+    log('  Instruction-file only (no hooks/MCP) — a portable memory-awareness rung for tools that read AGENTS.md.');
+  } else {
+    log('  Restart the agent to activate. Complete install — one step, no separate command.');
+  }
+
+  if (scaffold.errors.length > 0) {
+    for (const e of scaffold.errors) logError(`  error: ${e.path}: ${e.error}`);
+    process.exitCode = 1;
+  }
+}
+
+/**
+ * Task 50.J/50.L — `cmk hook <event>` — the Kiro hook entrypoint.
+ *
+ * Kiro's IDE + CLI hooks call `cmk hook <event>` (agentSpawn / promptSubmit /
+ * stop / preToolUse). Unlike Claude Code's hook bins (which read a stdin JSON
+ * payload), Kiro passes context via argv + env + cwd + its transcript file
+ * (probe-verified, P-CJYGTQYR). runKiroHook adapts that to the kit's cores.
+ *
+ * ALWAYS exits 0 EXCEPT a deliberate preToolUse BLOCK (exit 2 → the memory
+ * delete-guardrail, D-192). A crashed hook still exits 0 (fail-open).
+ */
+/**
+ * Extract the about-to-run TOOL COMMAND from a preToolUse hook payload, for the
+ * memory delete-guardrail (D-192).
+ *
+ * Kiro's `preToolUse` delivers `{ tool_name, tool_input: { command } }` on STDIN
+ * — the SAME shape as Claude Code (VERIFIED from the real oh-my-kiro + vibekit
+ * preToolUse hooks: `cat | jq '.tool_input.command'`). So the production guard
+ * uses the `cmk-guard-memory` bin directly (it reads that stdin); this helper is
+ * the forward-compat path if a `cmk hook preToolUse` is ever wired instead. A
+ * `.command` fallback covers a flattened payload. No match → '' (fail-open).
+ */
+export function kiroToolCommand(payload, _cwd) {
+  const p = payload || {};
+  const cmd = p.tool_input?.command ?? p.command;
+  return typeof cmd === 'string' ? cmd : '';
+}
+
+export function runHook(event, _options = {}, _command, deps = {}) {
+  const log = deps.log ?? ((s) => process.stdout.write(s));
+  const logError = deps.logError ?? ((s) => process.stderr.write(`${s}\n`));
+  // The Kiro hook payload. Most events (agentSpawn/promptSubmit/stop/preToolUse)
+  // get their input from argv + env (USER_PROMPT) + cwd + transcript, NOT stdin —
+  // and runHook must NOT blocking-read fd 0 for them (a dangling-open `runCommand`
+  // stdin would hang the hook to its timeout — B1, the skill-review catch).
+  //
+  // postToolUse (50.N.2) is the ONE event whose data (tool_name/tool_input/
+  // tool_response) has no env fallback — it arrives as a STDIN JSON payload. We
+  // read stdin ONLY for postToolUse, TTY-guarded (readHookStdin returns '' on a
+  // TTY). Tests inject `deps.payload` to bypass the read entirely.
+  //
+  // WHY THIS IS SAFE (the precedent, not a guess): the kit ALREADY ships a
+  // stdin-reading hook in the SAME kiro-cli agent config — `cmk-guard-memory`
+  // (preToolUse) reads stdin the identical way (readHookStdin → readFileSync(0)).
+  // preToolUse and postToolUse are siblings in the same Amazon-Q hook contract,
+  // both delivering {tool_name, tool_input, …} on a piped-and-closed stdin. If
+  // Kiro left that stdin dangling-open, the already-merged guard would hang on
+  // every shell command — it doesn't. So this read rests on the same (verified-by-
+  // -contract-shape) assumption the guard already relies on, NOT a new risk.
+  // The 50.N.1 B1 fix removed a stdin read for events that have an ENV fallback
+  // (the prompt) — postToolUse has none, so the read is necessary here.
+  // VERIFICATION (surfaced, not buried): the live stdin-close + payload-shape
+  // assumption both this leg AND the preToolUse guard depend on is a BLOCKING
+  // cut-gate item (KG-observe, paired with KG-guard) — one real kiro-cli fs_write
+  // verifies both. Until that passes live, this leg is "structurally wired,
+  // live-unverified" (stated in the PR body + the 50.N.2 task, per the no-disclaimer
+  // -ships-latent rule).
+  let payload = deps.payload;
+  if (payload === undefined) {
+    if (event === 'postToolUse') {
+      try {
+        const readStdin = deps.readStdin ?? (() => readHookStdin({ isTTY: process.stdin.isTTY }));
+        const raw = readStdin();
+        payload = raw && raw.trim() !== '' ? JSON.parse(raw) : {};
+      } catch {
+        payload = {};
+      }
+    } else {
+      payload = {};
+    }
+  }
+  const r = runKiroHook({
+    argv: [event],
+    cwd: deps.cwd ?? process.cwd(),
+    env: deps.env ?? process.env,
+    payload,
+    deps: {
+      readKiroTurn: deps.readKiroTurn ?? readKiroTurn,
+      // injectContext returns the assembled context string; normalize to {text}.
+      // userDir is passed through so cross-project user-tier memory surfaces on
+      // Kiro inject too (injectContext resolves $MEMORY_KIT_USER_DIR when userDir
+      // is absent, but pass it explicitly when the caller provides one).
+      inject: deps.inject ?? ((args) => {
+        const text = injectContext({ cwd: args.cwd, ...(args.userDir ? { userDir: args.userDir } : {}) });
+        return { ok: true, text: typeof text === 'string' ? text : text?.text ?? '' };
+      }),
+      // Pass a RESOLVED autoExtractPath so captureTurn can spawn the detached
+      // auto-extract child (D-200 — else no extraction, no wedge promotion). The
+      // `captureTurn` impl is injectable (deps.captureTurn) so a test can assert
+      // the autoExtractPath is forwarded WITHOUT replacing the whole capture dep
+      // (replacing `capture` would bypass the very wiring under test).
+      capture: deps.capture ?? ((args) => (deps.captureTurn ?? captureTurn)({
+        payload: args.payload,
+        projectRoot: args.projectRoot,
+        autoExtractPath: resolveKiroAutoExtractPath(deps.env ?? process.env),
+      })),
+      // 50.N.1 — prompt-capture on the prompt-submit events (the <private>-strip
+      // + transcript-append half of Claude Code's UserPromptSubmit). Best-effort;
+      // the dispatcher swallows a throw so inject still runs.
+      capturePrompt: deps.capturePrompt ?? ((args) => capturePrompt({
+        payload: args.payload,
+        projectRoot: args.projectRoot,
+      })),
+      // 50.N.2 — postToolUse → observe-edit (the file-edit observation leg). The
+      // bin maps Kiro's fs_write → Write before this runs. Best-effort.
+      observe: deps.observe ?? ((args) => observeEdit({
+        payload: args.payload,
+        projectRoot: args.projectRoot,
+      })),
+      // preToolUse → the memory delete-guardrail (D-192). Reads the about-to-run
+      // tool command out of the Kiro payload and returns {block, reason?}.
+      guard: deps.guard ?? ((args) => decideGuard(kiroToolCommand(args.payload, args.cwd))),
+    },
+  });
+  if (r.stdout) log(r.stdout);
+  if (r.stderr) logError(r.stderr);
+  // The always-exit-0 invariant holds for EVERY event EXCEPT a deliberate
+  // preToolUse BLOCK (exit 2 → Kiro blocks the tool, D-192). Honor the
+  // dispatcher's exitCode (0 for inject/capture/noop/error; 2 only on a guard
+  // block) instead of hardcoding 0 — a crashed guard still fails open (the
+  // dispatcher's catch returns exitCode 0).
+  process.exitCode = typeof r.exitCode === 'number' ? r.exitCode : 0;
+}
+
+/**
+ * `cmk uninstall [--ide <agent>]` — remove ONE agent's kit-managed surface,
+ * scoped by `--ide` exactly like `cmk install` (D-189). Default (no flag)
+ * removes the Claude Code surface (the CLAUDE.md managed block); `--ide kiro`
+ * removes the Kiro surface (the .kiro/ managed blocks + skills + IDE hooks + the
+ * guarded ~/.aws CLI agent + the AGENTS.md block). BOTH are conservative: they
+ * NEVER touch context/, context.local/, the user tier, or .gitignore — the
+ * shared brain is sacred. Everything outside the kit's markers is byte-preserved.
+ */
+export function runUninstall(options /*, command */) {
+  const projectRoot = resolvePath((options && options.cwd) || process.cwd());
+  const ide = (options && options.ide) || 'claude-code';
+  // Injectable log sinks (mirror runInstall) so tests can capture output.
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
+
+  if (ide === 'kiro') {
+    const r = uninstallKiro({ projectRoot, awsDir: options?.awsDir });
+    log(
+      `cmk uninstall (kiro): ${r.changed ? 'removed the Kiro managed surface' : 'nothing to remove'} — context/ preserved.`,
+    );
+    return;
+  }
+  if (ide !== 'claude-code') {
+    logError(`cmk uninstall: unknown --ide '${ide}'. Supported: claude-code, kiro.`);
+    process.exitCode = 2;
+    return;
+  }
+
   const result = removeClaudeMdBlock({ projectRoot });
-  console.log(`cmk uninstall: CLAUDE.md=${result.action} (${result.path})`);
+  log(`cmk uninstall: CLAUDE.md=${result.action} (${result.path})`);
   if (result.action === 'not-found') {
-    console.log('  (no kit-managed block found; CLAUDE.md left unchanged)');
+    log('  (no kit-managed block found; CLAUDE.md left unchanged)');
   } else if (result.action === 'no-file') {
-    console.log('  (no CLAUDE.md to uninstall from)');
+    log('  (no CLAUDE.md to uninstall from)');
   }
 }
 
@@ -381,7 +683,10 @@ function runLessonsPromote(id, options = {}) {
  *   --include-tombstoned               (default false)
  */
 async function runSearch(queryParts, options) {
-  const projectRoot = resolvePath(process.cwd());
+  // --project <dir> overrides cwd (the kiro-cli fix, Kiro #4579 — no `cd` prefix).
+  const projectRoot = options?.project
+    ? resolvePath(normalizeProjectPath(options.project))
+    : resolvePath(process.cwd());
   const userDir =
     process.env.MEMORY_KIT_USER_DIR ?? join(homedir(), '.claude-memory-kit');
   const query = Array.isArray(queryParts) ? queryParts.join(' ') : queryParts;
@@ -763,7 +1068,13 @@ export function parseFactInput(options, { readFile, readStdin } = {}) {
 // (one model call, explicit path only). Commander awaits actions; the
 // terse-path tests were updated to await (contract change, intent preserved).
 export async function runRemember(textParts, options, deps = {}) {
-  const projectRoot = deps.projectRoot ?? resolvePath(process.cwd());
+  // --project <dir> overrides cwd (the kiro-cli fix, Kiro #4579): kiro-cli's
+  // command allowlist rejects a `cd … && cmk remember …` prefix, so the kiro-cli
+  // agent runs `cmk remember "<fact>" --project "<abs>"` with NO cd. normalize a
+  // git-bash `/c/Temp` path the model may emit → `C:/Temp`.
+  const projectRoot = options?.project
+    ? resolvePath(normalizeProjectPath(options.project))
+    : (deps.projectRoot ?? resolvePath(process.cwd()));
   const userDir =
     deps.userDir ?? process.env.MEMORY_KIT_USER_DIR ?? join(homedir(), '.claude-memory-kit');
   const log = deps.log ?? console.log;
@@ -1410,12 +1721,16 @@ export function runConfigCli(options /* , command */) {
 async function runRepairCli(options /* , command */) {
   const projectRoot = resolvePath(process.cwd());
   const userDir = join(homedir(), '.claude-memory-kit');
-  // Scope flags: --hooks / --locks / --index → run that one only.
-  // --all OR no flag → run all three.
+  // Scope flags: --hooks / --locks / --index / --format → run that one only.
+  // --all OR no flag → run all of them.
+  const only = (flag) =>
+    options?.[flag] &&
+    !['hooks', 'locks', 'index', 'format'].filter((f) => f !== flag).some((f) => options?.[f]);
   let scope;
-  if (options?.hooks && !options?.locks && !options?.index) scope = 'hooks';
-  else if (options?.locks && !options?.hooks && !options?.index) scope = 'locks';
-  else if (options?.index && !options?.hooks && !options?.locks) scope = 'index';
+  if (only('hooks')) scope = 'hooks';
+  else if (only('locks')) scope = 'locks';
+  else if (only('index')) scope = 'index';
+  else if (only('format')) scope = 'format';
   else scope = 'all';
 
   try {
@@ -1680,11 +1995,13 @@ async function runCompress(options /* , command */) {
 
 async function runMcpDispatch(childName) {
   if (childName === 'serve') {
-    // Claude Code sets CLAUDE_PROJECT_DIR in the spawned MCP server's environment
-    // to the project root (code.claude.com/docs/en/mcp). Prefer it over cwd so the
-    // server indexes the right project even when Claude Code launches it with a
-    // different working directory. Falls back to cwd for a manual `cmk mcp serve`.
-    const projectRoot = resolvePath(process.env.CLAUDE_PROJECT_DIR ?? process.cwd());
+    // Which project does this server serve? Claude Code sets CLAUDE_PROJECT_DIR in
+    // the spawned server's env; otherwise fall back to the launch cwd (or walk up
+    // to the nearest `context/`). The kiro-cli surface does NOT use MCP at all (its
+    // agent sets includeMcpJson:false — explicit memory goes through the `cmk
+    // remember`/`cmk search` shell commands), so this server is the Claude Code +
+    // Kiro IDE path. See resolveMcpProjectRoot in tier-paths.mjs.
+    const projectRoot = resolveMcpProjectRoot();
     const userDir = process.env.MEMORY_KIT_USER_DIR ?? join(homedir(), '.claude-memory-kit');
     // ALL logs to stderr per design §10.1; stdout is reserved for
     // JSON-RPC messages handled by the SDK's StdioServerTransport.
@@ -1966,6 +2283,7 @@ export const subcommands = [
     description: 'cross-OS one-shot install — scaffold 3-tier dirs + inject .gitignore + drop kit CLAUDE.md block + wire Claude Code hooks',
     milestone: 3,
     optionSpec: [
+      { flags: '--ide <agent>', description: 'target agent: claude-code (default) | kiro — wires that agent\'s hooks + MCP + instruction file' },
       { flags: '--force', description: 'allow downgrade of an existing newer-version CLAUDE.md block' },
       { flags: '--no-hooks', description: 'scaffold only; do NOT wire hooks into .claude/settings.json' },
       { flags: '--with-semantic', description: 'enable semantic recall: install the local embedder (~260 MB once), default search to hybrid, pre-warm the model' },
@@ -1974,10 +2292,20 @@ export const subcommands = [
     ],
     action: runInstall,
   },
+  {
+    name: 'hook',
+    description: 'Kiro hook entrypoint — `cmk hook <agentSpawn|promptSubmit|stop>` (inject/capture; called by Kiro IDE + CLI hooks, not by users)',
+    milestone: 50,
+    argSpec: [{ flags: '<event>', description: 'the Kiro lifecycle event: agentSpawn | promptSubmit | stop' }],
+    action: runHook,
+  },
   {
     name: 'uninstall',
-    description: 'remove the CLAUDE.md kit block (preserves everything else byte-for-byte)',
+    description: 'remove the kit-managed surface (preserves everything else byte-for-byte; never touches context/)',
     milestone: 4,
+    optionSpec: [
+      { flags: '--ide <agent>', description: 'which agent to uninstall: claude-code (default) | kiro — removes only THAT agent\'s managed surface' },
+    ],
     action: runUninstall,
   },
   {
@@ -2003,6 +2331,7 @@ export const subcommands = [
       { flags: '--links <a,b>', description: 'rich: related fact names for [[cross-links]]' },
       { flags: '--from-file <path>', description: 'rich: read the fact as a JSON object from a file — shell-safe (content never touches argv; the safe way to capture backtick/quote-heavy Why/How). JSON keys: text (required), why, how, type, title, links. Self-contained — other flags are ignored.' },
       { flags: '--json', description: 'rich: read the fact as a JSON object from stdin (pipe-safe, shell-safe) — same JSON keys as --from-file' },
+      { flags: '--project <dir>', description: 'project root to write to (default: cwd). Used by the kiro-cli agent — kiro-cli rejects a `cd … &&` prefix (Kiro #4579), so it passes the project root explicitly instead.' },
     ],
     action: runRemember,
   },
@@ -2019,6 +2348,7 @@ export const subcommands = [
       { flags: '--since <date>', description: 'ISO date — exclude observations older than this' },
       { flags: '--limit <n>', description: 'max results (default: 20)' },
       { flags: '--include-tombstoned', description: 'include deleted observations in results' },
+      { flags: '--project <dir>', description: 'project root to search (default: cwd). Used by the kiro-cli agent (no `cd` prefix — Kiro #4579).' },
     ],
     action: runSearch,
   },
@@ -2222,13 +2552,14 @@ export const subcommands = [
   },
   {
     name: 'repair',
-    description: 'idempotent self-repair — re-register hooks, reset stale locks, rebuild index',
+    description: 'idempotent self-repair — re-register hooks, reset stale locks, rebuild index, lint-clean memory',
     milestone: 39,
     optionSpec: [
       { flags: '--hooks', description: 're-register hooks from template (merges kit hooks into .claude/settings.json)' },
       { flags: '--locks', description: 'clear stale locks (>1h old by default)' },
       { flags: '--index', description: 'invoke `cmk reindex --full`' },
-      { flags: '--all', description: 'run all three repairs in order (default if no scope flag given)' },
+      { flags: '--format', description: 'migrate committed memory markdown to the lint-clean format (DECISIONS.md headings)' },
+      { flags: '--all', description: 'run all repairs in order (default if no scope flag given)' },
     ],
     action: runRepairCli,
   },
@@ -2305,7 +2636,9 @@ export const subcommands = [
     name: 'mcp',
     description: 'run the MCP server over stdio (invoked by Claude Code, not by humans)',
     milestone: 31,
-    children: [{ name: 'serve', description: 'start the stdio MCP server; JSON-RPC on stdin/stdout' }],
+    children: [
+      { name: 'serve', description: 'start the stdio MCP server; JSON-RPC on stdin/stdout' },
+    ],
     action: runMcpDispatch,
   },
   {

package/src/tier-paths.mjs

@@ -9,11 +9,92 @@
 //   resolveTierRoot({tier, projectRoot, userDir}) → absolute path
 //   resolveFactDir(tier, tierRoot) → absolute path to <memory|fragments>
 
+import { existsSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+
+// Canonicalize a path for comparison: resolve 8.3 short names (Windows
+// `TAMIR~1.BN-`) + symlinks to their real long form, so a short-name path and
+// its long-name twin compare equal. Falls back to `resolve(p)` if the path
+// doesn't exist (realpathSync throws on a missing path). Exported so the project
+// discovery in inject-context.mjs shares ONE implementation (Task 168 — the
+// home-boundary + canonicalize logic must not drift across the two walkers).
+export function canonicalPath(p) {
+  try {
+    return realpathSync.native ? realpathSync.native(p) : realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+}
+
+/**
+ * Walk up from `cwd` to the nearest ancestor that has one of the `markers`
+ * subdirs (a kit-installed project), STOPPING at the home directory — a stray
+ * `~/context/` (test debris, or a `cmk` run that scaffolded in home) must NOT be
+ * served as a project from an unrelated subdir (Task 168). Returns the discovered
+ * root, or `resolve(cwd)` if none found below home.
+ *
+ * @param {string} cwd            starting directory
+ * @param {string[]} markers      subdir names that mark a project root (e.g.
+ *                                ['context'] or ['context', 'context.local'])
+ */
+export function discoverRootUpward(cwd, markers = ['context']) {
+  const home = canonicalPath(homedir());
+  let dir = resolve(cwd);
+  // Defensive bound: walk no more than 64 ancestors.
+  for (let i = 0; i < 64; i++) {
+    const atHome = canonicalPath(dir) === home;
+    if (!atHome && markers.some((m) => existsSync(join(dir, m)))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break; // reached the filesystem root
+    if (atHome) break; // do not climb above $HOME into a stray ancestor context/
+    dir = parent;
+  }
+  return resolve(cwd); // last resort
+}
 
 export const VALID_TIERS = new Set(['U', 'P', 'L']);
 
+/**
+ * Normalize a project path that may arrive in a unix/git-bash form. kiro-cli's
+ * model sometimes emits a `/c/Temp/proj` style path (git-bash) for `--project`,
+ * which Windows `resolve()` mangles. Convert a leading `/<drive>/` → `<DRIVE>:/`.
+ * A normal Windows or POSIX absolute path passes through unchanged. Used by
+ * `cmk remember`/`cmk search` --project (the kiro-cli explicit-memory path).
+ */
+export function normalizeProjectPath(p) {
+  if (typeof p !== 'string') return p;
+  const m = /^\/([a-zA-Z])\/(.*)$/.exec(p); // /c/Temp/proj  →  c , Temp/proj
+  if (m) return `${m[1].toUpperCase()}:/${m[2]}`;
+  return p;
+}
+
+/**
+ * Resolve which project `cmk mcp serve` should serve (the Claude Code + Kiro IDE
+ * MCP path — kiro-cli doesn't use MCP). The MCP server is a long-lived child the
+ * agent launches, so it can't just trust cwd.
+ *
+ * Precedence: CLAUDE_PROJECT_DIR (Claude Code sets it in the spawned env) → walk
+ * UP from cwd to the nearest `context/` ancestor → cwd (last resort). Pure (env +
+ * cwd injected) so it's unit-testable without spawning.
+ *
+ * @param {object} [opts]
+ * @param {Record<string,string|undefined>} [opts.env=process.env]
+ * @param {string} [opts.cwd=process.cwd()]
+ * @returns {string} the resolved project root (absolute)
+ */
+export function resolveMcpProjectRoot({ env = process.env, cwd = process.cwd() } = {}) {
+  const fromClaude = env.CLAUDE_PROJECT_DIR;
+  if (fromClaude && fromClaude.trim() !== '') return resolve(fromClaude);
+
+  // Walk up to the nearest `context/`-bearing project, STOPPING at home (Task 168
+  // — a stray `~/context/` must not be served from an unrelated subdir; a real
+  // project's context/ lives below home, or via the explicit CLAUDE_PROJECT_DIR
+  // handled above). Shared with inject-context's discoverProjectRoot via the
+  // single discoverRootUpward implementation.
+  return discoverRootUpward(cwd, ['context']);
+}
+
 // Matches IDs produced by @lh8ppl/cmk-canonicalize.generateId(). Tier prefix +
 // 8 chars from the custom 32-char base32 alphabet that excludes the six
 // ambiguous chars (0, O, 1, l, I, 8). See design §3.1.

package/src/weekly-curate.mjs

@@ -47,6 +47,7 @@ import {
 } from './cooldown.mjs';
 import { dailyDistill } from './daily-distill.mjs';
 import { autoPersona } from './auto-persona.mjs';
+import { trimTrailingNewlines } from './managed-block.mjs';
 import { initUserTier } from './install.mjs';
 import { autoDrainQueues } from './auto-drain.mjs';
 
@@ -449,8 +450,11 @@ export async function weeklyCurate({
   // Append to archive.md (NOT overwrite — archive is append-only history).
   const archivePath = archiveMdPath(projectRoot);
   mkdirSync(join(projectRoot, ...SESSIONS_REL), { recursive: true });
-  const suffix = dedupedOutput.endsWith('\n') ? '' : '\n';
-  appendFileSync(archivePath, dedupedOutput + suffix + '\n', 'utf8');
+  // Lint-clean append (MD012 no-multiple-blanks): the old `dedupedOutput + suffix
+  // + '\n'` could yield THREE consecutive newlines when Haiku output already ended
+  // in a blank line. Trim trailing newlines (ReDoS-safe helper), then append
+  // exactly one blank-line separator (`\n\n`).
+  appendFileSync(archivePath, `${trimTrailingNewlines(dedupedOutput)}\n\n`, 'utf8');
 
   // Delete OLD today-*.md files (audit retention via git history;
   // committed tier per .gitignore.fragment).

package/template/.claude/skills/memory-search/SKILL.md

@@ -1,6 +1,19 @@
 ---
 name: memory-search
-description: Searches the project's recorded memory (claude-memory-kit) — decisions, conventions, architecture, the reasoning behind choices, and where things live — and returns a curated, cited summary. Fire whenever the answer might be something the project already established in past work, HOWEVER the question is phrased — any prior decision, convention, rationale, or "how/where/why is it this way" question, including oblique or roundabout asks ("why is everything so spread out?", "remind me what we settled on for X", "how come these files are tiny?"). Also fire when a "[claude-memory-kit] Memory available" hint appears on the prompt. The examples are illustrative, not a checklist — prefer recalling over re-deriving an answer from the code. The session-start snapshot is a bounded index; this skill reaches the rest. Skip only when the question is purely about uncommitted or just-edited live code that memory cannot know, concerns this conversation only, or the user asked to ignore memory.
+description: >-
+  Searches the project's recorded memory (claude-memory-kit) — decisions,
+  conventions, architecture, the reasoning behind choices, and where things live
+  — and returns a curated, cited summary. Fire whenever the answer might be
+  something the project already established in past work, HOWEVER the question is
+  phrased — any prior decision, convention, rationale, or "how/where/why is it
+  this way" question, including oblique or roundabout asks ("why is everything so
+  spread out?", "remind me what we settled on for X", "how come these files are
+  tiny?"). Also fire when a "[claude-memory-kit] Memory available" hint appears on
+  the prompt. The examples are illustrative, not a checklist — prefer recalling
+  over re-deriving an answer from the code. The session-start snapshot is a
+  bounded index; this skill reaches the rest. Skip only when the question is
+  purely about uncommitted or just-edited live code that memory cannot know,
+  concerns this conversation only, or the user asked to ignore memory.
 context: fork
 allowed-tools: mcp__cmk__mk_search mcp__cmk__mk_get mcp__cmk__mk_timeline mcp__cmk__mk_recent_activity Bash(cmk search *) Bash(cmk get *) Bash(cmk timeline *) Bash(cmk recent-activity *)
 ---