@lh8ppl/claude-memory-kit 0.3.5 → 0.4.0

package/src/kiro-trusted-commands.mjs

@@ -0,0 +1,130 @@
+// kiro-trusted-commands.mjs — pre-trust the kit's Kiro hook commands (D-194).
+//
+// THE PROBLEM (found live in the v0.4.0 cut-gate-kiro, 50.M): Kiro gates a hook's
+// shell command behind a "Run / Reject" approval prompt unless it's pre-trusted
+// (kiro.dev/docs/cli/chat/permissions). So the kit's inject/capture/guard hooks —
+// `cmd.exe /c cmk hook promptSubmit`, etc. — prompt the user EVERY turn, and
+// "automatic memory" isn't automatic. On Claude Code a registered hook just fires;
+// on Kiro it must be trusted (the 6th cross-agent "Claude-Code-shaped assumption"
+// cut-blocker — D-185/186/187/188/190).
+//
+// THE FIX: write the kit's OWN hook-command prefixes into the WORKSPACE
+// `.vscode/settings.json` under `kiroAgent.trustedCommands` — Kiro's IDE
+// command-trust list (an array of wildcard-PREFIX patterns; `npm *` trusts any
+// command starting `npm `). Workspace scope (not the user-global
+// `…/Kiro/User/settings.json`) so the trust travels with the repo and never
+// touches the user's machine-wide trust.
+//
+// We trust ONLY the kit's own commands by SPECIFIC prefix — never the
+// over-permissive `cmd.exe /c *` or `*` (the docs warn wildcards over-trust, and
+// trust matches only the command PREFIX, so a broad prefix would also trust any
+// chained command after it).
+//
+// Disciplines (same as mutateAgentConfig): array-UNION (a user's existing trusted
+// commands are preserved + deduped, never clobbered), refuse-to-clobber on a
+// corrupt file, BOM-tolerant read (D-187), idempotent, atomic write. Uninstall
+// removes ONLY our patterns and prunes an emptied key (no orphan empty array) —
+// the over-mutation guard.
+//
+// Public surface:
+//   installKiroTrustedCommands({ projectRoot }) → { action, changed, path }
+//   uninstallKiroTrustedCommands({ projectRoot }) → { action, changed, path }
+//   kitTrustedCommandPatterns() → string[]  (the patterns we own — also the
+//                                            uninstall key + the doctor/gate check)
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseJsonFile } from './read-json.mjs';
+import { atomicWrite } from './mutate-agent-config.mjs';
+import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
+
+const SETTINGS_PATH = ['.vscode', 'settings.json'];
+const TRUSTED_KEY = 'kiroAgent.trustedCommands';
+
+const IS_WINDOWS = process.platform === 'win32';
+
+// The kit's hook commands, as TRUST PREFIXES. These must prefix-match the actual
+// commands kiro-hook-command.mjs emits:
+//   IDE/CLI hooks → `[cmd.exe /c ]cmk hook <event>`   → `…cmk hook *`
+//   delete-guard  → `[cmd.exe /c ]cmk-guard-memory`   → `…cmk-guard-memory*`
+// Windows wraps in `cmd.exe /c ` (the WSL-no-node finding, P-PM2CD6CB); POSIX runs
+// the bare command. We keep these in lockstep with kiro-hook-command.mjs by
+// mirroring its exact platform prefix — a SPECIFIC prefix, not a blanket wildcard.
+const WIN_PREFIX = 'cmd.exe /c ';
+export function kitTrustedCommandPatterns() {
+  const base = ['cmk hook *', 'cmk-guard-memory*'];
+  return IS_WINDOWS ? base.map((b) => WIN_PREFIX + b) : base;
+}
+
+// Read settings.json, distinguishing missing (→ {}) from corrupt (→ throw-marker).
+// BOM-tolerant: a Windows-editor BOM must not read as corrupt (D-187). Returns
+// { root } on success or { error } on a genuine parse failure (refuse-to-clobber).
+function readSettings(path) {
+  if (!existsSync(path)) return { root: {} };
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (err) {
+    return { error: `could not read ${path}: ${err.message}` };
+  }
+  if (raw.trim() === '') return { root: {} };
+  // parseJsonFile strips the BOM and returns the sentinel on bad JSON.
+  const CORRUPT = Symbol('corrupt');
+  const parsed = parseJsonFile(path, { fallback: CORRUPT });
+  if (parsed === CORRUPT) return { error: `${path} is not valid JSON — refusing to overwrite` };
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { error: `${path} is valid JSON but not an object — refusing to overwrite` };
+  }
+  return { root: parsed };
+}
+
+export function installKiroTrustedCommands({ projectRoot } = {}) {
+  if (!projectRoot) throw new Error('installKiroTrustedCommands: projectRoot is required');
+  const path = join(projectRoot, ...SETTINGS_PATH);
+  const fileExists = existsSync(path);
+
+  const { root, error } = readSettings(path);
+  if (error) return errorResult({ category: ERROR_CATEGORIES.CONFIG_PARSE, errors: [error], changed: false, path });
+
+  const existing = Array.isArray(root[TRUSTED_KEY]) ? root[TRUSTED_KEY] : [];
+  const want = kitTrustedCommandPatterns();
+
+  // array-UNION: keep the user's entries (and order), append only the kit
+  // patterns not already present. Idempotent: if all ours are present, no write.
+  const missing = want.filter((p) => !existing.includes(p));
+  if (missing.length === 0) return { action: 'skipped', changed: false, path };
+
+  const next = { ...root, [TRUSTED_KEY]: [...existing, ...missing] };
+  atomicWrite(path, `${JSON.stringify(next, null, 2)}\n`);
+  return { action: 'installed', changed: true, path, created: !fileExists };
+}
+
+export function uninstallKiroTrustedCommands({ projectRoot } = {}) {
+  if (!projectRoot) throw new Error('uninstallKiroTrustedCommands: projectRoot is required');
+  const path = join(projectRoot, ...SETTINGS_PATH);
+  if (!existsSync(path)) return { action: 'noop', changed: false, path };
+
+  const { root, error } = readSettings(path);
+  // A corrupt file on uninstall: leave it alone (don't error-out the whole
+  // uninstall; just report no change for this leg).
+  if (error || !Array.isArray(root[TRUSTED_KEY])) return { action: 'noop', changed: false, path };
+
+  // Ownership is by exact-string membership (skill-review M1): if a user had
+  // MANUALLY added a pattern byte-identical to one of ours, uninstall removes it
+  // too — we can't distinguish who added an identical string without a separate
+  // ownership-marker array, which would be over-engineering for this surface.
+  // Collision is near-zero (our patterns are kit-specific: `cmd.exe /c cmk hook *`).
+  const ours = new Set(kitTrustedCommandPatterns());
+  const kept = root[TRUSTED_KEY].filter((c) => !ours.has(c));
+  if (kept.length === root[TRUSTED_KEY].length) return { action: 'noop', changed: false, path };
+
+  const next = { ...root };
+  if (kept.length === 0) {
+    // prune an emptied key — no orphan empty array left behind.
+    delete next[TRUSTED_KEY];
+  } else {
+    next[TRUSTED_KEY] = kept;
+  }
+  atomicWrite(path, `${JSON.stringify(next, null, 2)}\n`);
+  return { action: 'uninstalled', changed: true, path };
+}

package/src/managed-block.mjs

@@ -0,0 +1,138 @@
+// managed-block.mjs — shared helpers for agent-config + instruction-file writes.
+//
+// install-agent.mjs (the generic per-agent installer) and install-kiro.mjs (the
+// Kiro 4-surface orchestrator) both need the same primitives: a managed
+// marker-block instruction-file writer, JSON-key removal that preserves siblings,
+// empty-parent pruning, and the non-regex newline trims (ReDoS-safe). These were
+// duplicated verbatim across the two; centralizing them here removes the drift
+// hazard (the kit's shared-module discipline — the same lesson the duplicated
+// atomicWrite taught earlier in Task 50).
+//
+// Public surface:
+//   writeManagedBlock(path, {body, frontmatter, markStart, markEnd}) → changed:bool
+//   removeManagedBlock(path, {markStart, markEnd}) → changed:bool
+//   removeJsonKey(path, keyPath) → changed:bool   (preserves siblings)
+//   pruneEmptyParent(path, keyPath) → void         (drops an emptied {} we leave)
+//   escapeRe / trimLeadingNewlines / trimTrailingNewlines (ReDoS-safe utils)
+
+import { existsSync, readFileSync } from 'node:fs';
+import { atomicWrite } from './mutate-agent-config.mjs';
+
+export const DEFAULT_MARK_START = '<!-- claude-memory-kit:start -->';
+export const DEFAULT_MARK_END = '<!-- claude-memory-kit:end -->';
+
+/**
+ * Write/refresh a managed marker block in an instruction file, byte-preserving
+ * everything outside the markers. `frontmatter` (e.g. Kiro's `inclusion: always`)
+ * is prepended only when the file is created fresh. Idempotent: identical content
+ * → no write, returns false.
+ * @returns {boolean} whether a write happened.
+ */
+export function writeManagedBlock(path, { body, frontmatter = '', markStart = DEFAULT_MARK_START, markEnd = DEFAULT_MARK_END } = {}) {
+  const block = `${markStart}\n${body}\n${markEnd}`;
+  const desired = `${frontmatter}${block}\n`;
+  const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+
+  let next;
+  if (existing === '') {
+    next = desired;
+  } else if (existing.includes(markStart) && existing.includes(markEnd)) {
+    // refresh in place — replace only the managed block, byte-preserve the rest.
+    next = existing.replace(
+      new RegExp(`${escapeRe(markStart)}[\\s\\S]*?${escapeRe(markEnd)}`),
+      block,
+    );
+  } else {
+    // append our block to the user's existing file.
+    next = `${trimTrailingNewlines(existing)}\n\n${block}\n`;
+  }
+
+  if (next === existing) return false;
+  atomicWrite(path, next);
+  return true;
+}
+
+/** Strip our managed block (+ surrounding blank lines), byte-preserve the rest. */
+export function removeManagedBlock(path, { markStart = DEFAULT_MARK_START, markEnd = DEFAULT_MARK_END } = {}) {
+  if (!existsSync(path)) return false;
+  const existing = readFileSync(path, 'utf8');
+  if (!existing.includes(markStart)) return false;
+  // The inner [\s\S]*? is lazy + bounded by two fixed literal delimiters → linear,
+  // not ReDoS-prone. Newline trims are non-regex (no `\n*$`/`^\n+` super-linear
+  // shapes); the `\n{3,}` collapse is a bounded quantifier, also linear.
+  const blockRe = new RegExp(`${escapeRe(markStart)}[\\s\\S]*?${escapeRe(markEnd)}`);
+  const stripped = trimLeadingNewlines(existing.replace(blockRe, '').replace(/\n{3,}/g, '\n\n'));
+  atomicWrite(path, stripped);
+  return true;
+}
+
+/**
+ * Remove a nested key from a JSON file, preserving everything else. Skips
+ * (returns false) on a missing file / parse error (never clobbers a corrupt file).
+ * @returns {boolean} whether a change was written.
+ */
+export function removeJsonKey(path, keyPath) {
+  if (!existsSync(path)) return false;
+  let root;
+  try {
+    root = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return false;
+  }
+  let cur = root;
+  for (let i = 0; i < keyPath.length - 1; i += 1) {
+    if (!cur || typeof cur !== 'object' || !(keyPath[i] in cur)) return false;
+    cur = cur[keyPath[i]];
+  }
+  const last = keyPath[keyPath.length - 1];
+  if (!cur || typeof cur !== 'object' || !(last in cur)) return false;
+  delete cur[last];
+  atomicWrite(path, `${JSON.stringify(root, null, 2)}\n`);
+  return true;
+}
+
+/**
+ * If the object at keyPath exists and is now empty ({}), remove it — so an
+ * uninstall doesn't leave a kit-shaped `{"mcpServers":{}}` husk. No-op on a
+ * missing file / parse error / non-empty target.
+ */
+export function pruneEmptyParent(path, keyPath) {
+  if (!existsSync(path)) return;
+  let root;
+  try {
+    root = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return;
+  }
+  let cur = root;
+  for (let i = 0; i < keyPath.length - 1; i += 1) {
+    if (!cur || typeof cur !== 'object' || !(keyPath[i] in cur)) return;
+    cur = cur[keyPath[i]];
+  }
+  const last = keyPath[keyPath.length - 1];
+  const target = cur && typeof cur === 'object' ? cur[last] : undefined;
+  if (target && typeof target === 'object' && !Array.isArray(target) && Object.keys(target).length === 0) {
+    delete cur[last];
+    atomicWrite(path, `${JSON.stringify(root, null, 2)}\n`);
+  }
+}
+
+// ── ReDoS-safe string utils ──────────────────────────────────────────────────
+
+export function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Non-regex newline trims — avoid the `\n*$` / `^\n+` super-linear-backtracking
+// shapes a static analyzer (rightly) flags as ReDoS-prone. O(n), no backtracking.
+export function trimTrailingNewlines(s) {
+  let end = s.length;
+  while (end > 0 && s[end - 1] === '\n') end -= 1;
+  return s.slice(0, end);
+}
+
+export function trimLeadingNewlines(s) {
+  let start = 0;
+  while (start < s.length && s[start] === '\n') start += 1;
+  return s.slice(start);
+}

package/src/memory-write.mjs

@@ -203,6 +203,27 @@ function findMatchingBullet({ lines, substring, sectionTitle }) {
   return null;
 }
 
+// Strip a bullet + its provenance comment (lines bulletIdx..commentIdx) and
+// collapse a resulting double blank line at the seam, so removing a bullet from
+// a blank-padded scratchpad doesn't leave two adjacent blank lines (MD012
+// no-multiple-blanks). Only the seam is touched — blanks elsewhere are
+// preserved. The bullet↔comment pair is removed together (the adjacency
+// invariant the whole kit depends on).
+function stripBulletPair(lines, bulletIdx, commentIdx) {
+  const kept = [...lines.slice(0, bulletIdx), ...lines.slice(commentIdx + 1)];
+  // If the splice put a blank line directly after a blank line at the seam,
+  // drop one. The seam is at index `bulletIdx` in `kept`.
+  if (
+    bulletIdx > 0 &&
+    bulletIdx < kept.length &&
+    kept[bulletIdx - 1].trim() === '' &&
+    kept[bulletIdx].trim() === ''
+  ) {
+    kept.splice(bulletIdx, 1);
+  }
+  return kept.join('\n');
+}
+
 // --- Tombstone writer (design §6.5) --------------------------------
 
 function writeTombstone({
@@ -438,10 +459,7 @@ function doReplace(opts) {
     });
   }
   // Strip the matched bullet + provenance comment.
-  const stripped = [
-    ...lines.slice(0, match.bulletIdx),
-    ...lines.slice(match.commentIdx + 1),
-  ].join('\n');
+  const stripped = stripBulletPair(lines, match.bulletIdx, match.commentIdx);
   writeFileSync(path, stripped, 'utf8');
 
   // Append the new bullet via the GUARDED inner path. We already ran
@@ -550,10 +568,7 @@ function doRemove(opts) {
   });
 
   // Strip from scratchpad.
-  const stripped = [
-    ...lines.slice(0, match.bulletIdx),
-    ...lines.slice(match.commentIdx + 1),
-  ].join('\n');
+  const stripped = stripBulletPair(lines, match.bulletIdx, match.commentIdx);
   writeFileSync(path, stripped, 'utf8');
 
   appendAuditEntry(tierRoot, {

package/src/mutate-agent-config.mjs

@@ -0,0 +1,243 @@
+// mutate-agent-config.mjs — the shared per-agent config-write PRIMITIVE.
+//
+// Task 50 (cross-agent install). This is the one piece of machinery the whole
+// `cmk install --ide <agent>` seam rests on: a single, tested function that
+// writes the kit's entry (an MCP-server registration, a hook entry) into ANY
+// agent's config file WITHOUT clobbering the user's other keys.
+//
+// The D-180 finding (research note 2026-06-20): do NOT build a per-agent
+// `Installer` base class — claude-mem proved it breaks the moment agents differ
+// in format/mechanism, and its ~6 bespoke config writers drifted in rigor (one
+// surgical, one whole-file-clobber, one that discards user config on a JSON
+// parse error). What actually generalizes is THIS primitive. Each per-agent
+// profile is then just DATA (where the file is, which key, which format).
+//
+// The kit's existing disciplines, applied to third-party files:
+//   - touch-only-our-keys      = the marker-block byte-preservation invariant
+//   - refuse-on-parse-error    = the safe-write / Poison_Guard fail-closed rule
+//   - atomic (tmp + rename)    = the same pattern compress-session/persona use
+//   - idempotent changed-bool  = re-running install is a no-op (Codex's pattern)
+//
+// Public surface (one function — a deep module, narrow interface):
+//
+//   mutateAgentConfig({ path, format, keyPath, entry, mode? }) → result
+//
+//     path     absolute path to the agent's config file (may not exist yet)
+//     format   'json'  (v0.4.0; 'yaml' / 'toml' deferred until an agent needs them)
+//     keyPath  array of keys to the slot we own, e.g. ['mcpServers', 'claude-memory-kit']
+//     entry    the object to place at keyPath
+//     mode     'merge' (default — deep-merge into an existing entry) | 'replace'
+//
+//   Result shape (result-shapes.mjs conventions):
+//     { action: 'created'|'updated'|'skipped'|'error', changed: boolean, path,
+//       errorCategory?, errors? }
+//       created  — the file did not exist; we created it with just our key
+//       updated  — the file existed; our key was added/changed (siblings preserved)
+//       skipped  — our key already matched exactly; nothing written (changed:false)
+//       error    — input invalid (schema) or target unparseable (config_parse);
+//                  NEVER writes on error
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { dirname, basename, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
+import { stripBom } from './read-json.mjs';
+
+const SUPPORTED_FORMATS = new Set(['json']);
+
+/**
+ * Write the kit's entry into an agent config file, preserving everything else.
+ * @returns {{action:string, changed:boolean, path:string, errorCategory?:string, errors?:string[]}}
+ */
+export function mutateAgentConfig({ path, format, keyPath, entry, mode = 'merge' }) {
+  // ── input validation (schema) ───────────────────────────────────────────
+  if (typeof path !== 'string' || path.length === 0) {
+    return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors: ['path must be a non-empty string'], changed: false });
+  }
+  if (!SUPPORTED_FORMATS.has(format)) {
+    return errorResult({
+      category: ERROR_CATEGORIES.SCHEMA,
+      errors: [`unsupported format ${JSON.stringify(format)} — supported: ${[...SUPPORTED_FORMATS].join(', ')}`],
+      changed: false,
+      path,
+    });
+  }
+  if (!Array.isArray(keyPath) || keyPath.length === 0 || !keyPath.every((k) => typeof k === 'string' && k.length > 0)) {
+    return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors: ['keyPath must be a non-empty array of non-empty strings'], changed: false, path });
+  }
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+    return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors: ['entry must be a plain object'], changed: false, path });
+  }
+  if (mode !== 'merge' && mode !== 'replace') {
+    return errorResult({ category: ERROR_CATEGORIES.SCHEMA, errors: [`mode must be 'merge' or 'replace', got ${JSON.stringify(mode)}`], changed: false, path });
+  }
+
+  // ── read existing (refuse-to-clobber on parse error) ─────────────────────
+  const fileExists = existsSync(path);
+  let root;
+  if (fileExists) {
+    let raw;
+    try {
+      // stripBom: a user's config file written by a Windows editor may carry a
+      // leading UTF-8 BOM, which would otherwise make the JSON.parse below refuse
+      // a perfectly valid file as "corrupt" (D-187). Strip only the BOM; the
+      // refuse-to-clobber-on-real-corruption guarantee below is unchanged.
+      raw = stripBom(readFileSync(path, 'utf8'));
+    } catch (err) {
+      return errorResult({ category: ERROR_CATEGORIES.CONFIG_PARSE, errors: [`could not read ${path}: ${err.message}`], changed: false, path });
+    }
+    if (raw.trim() === '') {
+      // an empty file is treated as an empty object (not a parse error)
+      root = {};
+    } else {
+      try {
+        root = JSON.parse(raw);
+      } catch (err) {
+        // The crucial guarantee: a corrupt target is NEVER overwritten.
+        return errorResult({ category: ERROR_CATEGORIES.CONFIG_PARSE, errors: [`${path} is not valid JSON — refusing to overwrite: ${err.message}`], changed: false, path });
+      }
+    }
+    if (root === null || typeof root !== 'object' || Array.isArray(root)) {
+      return errorResult({ category: ERROR_CATEGORIES.CONFIG_PARSE, errors: [`${path} is valid JSON but not an object — refusing to overwrite`], changed: false, path });
+    }
+  } else {
+    root = {};
+  }
+
+  // ── compute the next entry at keyPath ────────────────────────────────────
+  const existing = getAt(root, keyPath);
+  const nextEntry =
+    mode === 'merge' && isPlainObject(existing) ? deepMerge(existing, entry) : entry;
+
+  // idempotent: if our slot already deep-equals what we'd write, do nothing.
+  if (existing !== undefined && deepEqual(existing, nextEntry)) {
+    return { action: 'skipped', changed: false, path };
+  }
+
+  // ── apply + atomic write ─────────────────────────────────────────────────
+  const next = cloneDeep(root);
+  setAt(next, keyPath, nextEntry);
+
+  const serialized = `${JSON.stringify(next, null, 2)}\n`;
+  atomicWrite(path, serialized);
+
+  return { action: fileExists ? 'updated' : 'created', changed: true, path };
+}
+
+// ── internal helpers ───────────────────────────────────────────────────────
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function getAt(obj, keyPath) {
+  let cur = obj;
+  for (const k of keyPath) {
+    if (!isPlainObject(cur) || !(k in cur)) return undefined;
+    cur = cur[k];
+  }
+  return cur;
+}
+
+function setAt(obj, keyPath, value) {
+  let cur = obj;
+  for (let i = 0; i < keyPath.length - 1; i += 1) {
+    const k = keyPath[i];
+    if (!isPlainObject(cur[k])) cur[k] = {};
+    cur = cur[k];
+  }
+  cur[keyPath[keyPath.length - 1]] = value;
+}
+
+// Deep-merge `source` onto a copy of `target`. Objects merge recursively;
+// arrays + scalars from source replace target's (no array concat — replacing
+// args/command is the intended semantics).
+function deepMerge(target, source) {
+  const out = cloneDeep(target);
+  for (const [k, v] of Object.entries(source)) {
+    if (isPlainObject(v) && isPlainObject(out[k])) {
+      out[k] = deepMerge(out[k], v);
+    } else {
+      out[k] = cloneDeep(v);
+    }
+  }
+  return out;
+}
+
+function cloneDeep(v) {
+  return v === undefined ? undefined : JSON.parse(JSON.stringify(v));
+}
+
+function deepEqual(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+// Atomic write: serialize to a temp sibling, then rename over the target.
+// rename is atomic on the same filesystem, so a reader never sees a partial file.
+// Exported so install-agent.mjs (the per-agent wiring) shares ONE implementation
+// — the kit's shared-module discipline (no two copies to drift).
+//
+// Two Windows-specific hazards this guards against (BOTH real, BOTH surfaced by
+// the Task-50 stress runs — not "flakes": concrete EPERM-under-load failures):
+//   1. The tmp suffix is UNIQUE PER CALL (randomUUID), not `process.pid` — a
+//      single install sequence writes the same path several times (write →
+//      uninstall → prune) and vitest runs files concurrently in one worker
+//      (shared pid), so a pid-keyed tmp name could collide.
+//   2. `renameSync(tmp, target)` ONTO an existing file intermittently throws
+//      EPERM/EBUSY on Windows when the target is transiently locked (AV /
+//      indexer / another handle) under heavy parallel FS load. The kit already
+//      hit + documented this in persona-portability.mjs (restoreBackup); the
+//      proven fix is a short bounded retry. Without it, a `cmk install` on a
+//      busy Windows machine could spuriously fail mid-write.
+export function atomicWrite(path, contents) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(tmp, contents, 'utf8');
+    renameWithRetry(tmp, path);
+  } finally {
+    if (existsSync(tmp)) {
+      try {
+        unlinkSync(tmp);
+      } catch {
+        /* best-effort cleanup; the rename already succeeded or threw */
+      }
+    }
+  }
+}
+
+// renameSync with a bounded retry + BACKOFF on transient Windows EPERM/EBUSY
+// (the target briefly locked by AV/indexer/another handle under load). A
+// no-delay spin doesn't work — the lock lasts milliseconds while 5 immediate
+// retries finish in microseconds (the Task-50 stress proved this: retry fired
+// but exhausted instantly). So we sleep between attempts with a synchronous
+// backoff (Atomics.wait — real sync sleep, no busy-spin). A non-transient error
+// (e.g. ENOENT on the source) reraises immediately so we don't mask a real bug.
+//
+// `rename` + `sleep` are injectable so the retry policy is unit-testable WITHOUT
+// mocking node:fs or actually sleeping — production passes nothing.
+export function renameWithRetry(from, to, attempts = 8, rename = renameSync, sleep = sleepMs) {
+  let lastErr;
+  for (let i = 0; i < attempts; i += 1) {
+    try {
+      rename(from, to);
+      return;
+    } catch (err) {
+      if (err && (err.code === 'EPERM' || err.code === 'EBUSY' || err.code === 'EACCES')) {
+        lastErr = err; // transient lock under load — back off + retry
+        if (i < attempts - 1) sleep(Math.min(10 * 2 ** i, 250)); // 10,20,40…≤250ms
+        continue;
+      }
+      throw err; // anything else is a real error — don't mask it
+    }
+  }
+  throw lastErr;
+}
+
+// Synchronous sleep via Atomics.wait on a throwaway SharedArrayBuffer — blocks
+// the thread for `ms` without a CPU busy-spin. Used only on the (rare) Windows
+// transient-lock retry path, so the block is bounded + infrequent.
+function sleepMs(ms) {
+  if (ms <= 0) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}

package/src/read-json.mjs

@@ -0,0 +1,43 @@
+// read-json.mjs — BOM-tolerant JSON config reading.
+//
+// Windows editors (and PowerShell `Set-Content -Encoding utf8`) routinely write
+// a UTF-8 BOM (U+FEFF / EF BB BF) at the start of a file. A bare
+// `JSON.parse(readFileSync(path, 'utf8'))` throws on that leading BOM, so any kit
+// reader of a USER-AUTHORED config file (Amazon Q `settings.json`, an agent's
+// config) silently mis-reads a BOM'd file. The cut-gate-kiro live-test surfaced
+// this: the Kiro default-agent guard read a BOM'd `settings.json`, the parse
+// threw into its catch, and the guard concluded "no default agent set" — then
+// CLOBBERED the user's existing default (D-187; the same silent-clobber class as
+// D-184). These helpers make the kit's config reads BOM-tolerant; route every
+// USER-AUTHORED config JSON read through them (kiro-cli-agent, mutate-agent-
+// config, doctor HC-1, settings-hooks, config-core, semantic-backend).
+
+import { existsSync, readFileSync } from 'node:fs';
+
+/** Strip a single leading UTF-8 BOM if present. Non-string input passes through. */
+export function stripBom(text) {
+  if (typeof text !== 'string') return text;
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+/**
+ * Read + parse a JSON file, tolerating a leading BOM. Never throws: a missing
+ * file or malformed JSON returns `fallback` (default `undefined`) so callers can
+ * branch on the value instead of wrapping every read in try/catch.
+ *
+ * NOTE: missing-file and malformed-JSON both collapse to `fallback`. A caller
+ * that must DISTINGUISH the two (e.g. to surface a "parse error" message, or to
+ * refuse-to-clobber a corrupt file like mutate-agent-config / settings-hooks)
+ * should NOT use this — use `stripBom(readFileSync(...))` before its own parse.
+ *
+ * @param {string} path
+ * @param {{ fallback?: any }} [opts]
+ */
+export function parseJsonFile(path, { fallback = undefined } = {}) {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(stripBom(readFileSync(path, 'utf8')));
+  } catch {
+    return fallback;
+  }
+}

package/src/reindex.mjs

@@ -38,9 +38,22 @@ function extractHook(body) {
   return '';
 }
 
+// Wrap any bare http(s):// URL in angle brackets so it doesn't trip markdownlint
+// MD034 (no-bare-urls) when the INDEX ships in a user's committed repo. A URL
+// already inside `<…>` or `](…)` is left alone (the char before it isn't `<`/`(`).
+function autolinkBareUrls(text) {
+  return text.replace(/(^|[^<(])\b(https?:\/\/[^\s<>)\]]+)/g, '$1<$2>');
+}
+
 function formatIndexLine({ id, type, title, filename, hook }) {
-  const head = `- (${id}) [${type}] [${title}](${filename})`;
-  return hook ? `${head} — ${hook}` : head;
+  // Lint-clean the rendered INDEX line:
+  //   - the title goes inside `[title]` link text: trim + collapse internal
+  //     whitespace so a trailing space before `]` doesn't trip MD039
+  //     (no-space-in-links).
+  //   - the hook is trailing prose: wrap bare URLs (MD034).
+  const linkTitle = String(title ?? '').replace(/\s+/g, ' ').trim();
+  const head = `- (${id}) [${type}] [${linkTitle}](${filename})`;
+  return hook ? `${head} — ${autolinkBareUrls(hook)}` : head;
 }
 
 function listFactFiles(factDir) {