@lh8ppl/claude-memory-kit 0.3.5 → 0.4.1

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/register-crons.mjs

@@ -303,6 +303,37 @@ export function registerCron(opts = {}) {
     // schtasks path + the verbatim argv). Production never passes it.
     const spawn = opts.spawn ?? spawnSync;
     const r = spawn(schtasksExe, argv, { encoding: 'utf8', windowsHide: true, timeout: 10_000 });
+
+    // Task 167.E (D-207): set StartWhenAvailable so a missed nightly run (laptop
+    // asleep at 23:00) runs on wake instead of being silently dropped. schtasks
+    // /Create has NO CLI flag for this (verified — not in the help); it's settable
+    // only via XML or PowerShell. We use a follow-up PowerShell Set-ScheduledTask,
+    // BEST-EFFORT: a failure here never fails registration — the lazy roll
+    // (167.A/D) is the guarantee; this is a catch-up OPTIMIZATION. NB: this only
+    // covers a missed run while the machine is OFF/asleep; all OS catch-up
+    // mechanisms COALESCE multiple missed periods into one run (research note).
+    if (r.status === 0) {
+      const psExe = join(
+        process.env.SystemRoot || process.env.windir || 'C:\\Windows',
+        'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe',
+      );
+      const psScript =
+        `try { Set-ScheduledTask -TaskName '${entryName}' ` +
+        `-Settings (New-ScheduledTaskSettingsSet -StartWhenAvailable) ` +
+        `-ErrorAction Stop | Out-Null } catch { exit 1 }`;
+      try {
+        spawn(psExe, ['-NoProfile', '-NonInteractive', '-Command', psScript], {
+          encoding: 'utf8',
+          windowsHide: true,
+          timeout: 10_000,
+        });
+        // We intentionally ignore the PS exit status — registration already
+        // succeeded; catch-up is best-effort.
+      } catch {
+        // never let the catch-up call abort a successful registration
+      }
+    }
+
     return {
       action: r.status === 0 ? 'registered' : 'error',
       platform,

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) {

package/src/repair.mjs

@@ -16,8 +16,11 @@
 // Per design §14 + tasks.md 39 (39.1–39.3).
 
 import {
+  existsSync,
+  readFileSync,
   statSync,
   unlinkSync,
+  writeFileSync,
 } from 'node:fs';
 import { join } from 'node:path';
 import {
@@ -204,6 +207,34 @@ async function repairIndex({ projectRoot, userDir, reindexer }) {
   }
 }
 
+/**
+ * Migrate committed memory markdown to the lint-clean shape (Task 164.9) — so a
+ * repo installed before the lint-clean generators (164.1–164.7) brings its
+ * existing memory up to the clean format a default markdownlint passes. Today
+ * this normalizes `context/DECISIONS.md` (old `### ` entries → `## ` +
+ * blank-surrounded). Idempotent + CRLF-tolerant: a no-op on already-clean
+ * content (changed:false), so it's safe to run repeatedly. ONLY rewrites a file
+ * whose normalized form actually differs — never a gratuitous write.
+ */
+async function repairMemoryFormat({ projectRoot }) {
+  const { normalizeDecisionsJournal } = await import('./decisions-journal.mjs');
+  const decisionsPath = join(projectRoot, 'context', 'DECISIONS.md');
+  if (!existsSync(decisionsPath)) {
+    return { kind: 'format', changed: false, detail: 'no DECISIONS.md' };
+  }
+  try {
+    const before = readFileSync(decisionsPath, 'utf8');
+    const after = normalizeDecisionsJournal(before);
+    if (after === before) {
+      return { kind: 'format', changed: false, detail: 'DECISIONS.md already lint-clean' };
+    }
+    writeFileSync(decisionsPath, after, 'utf8');
+    return { kind: 'format', changed: true, detail: 'DECISIONS.md migrated to lint-clean headings' };
+  } catch (err) {
+    return { kind: 'format', changed: false, error: `format migration failed: ${err?.message ?? err}` };
+  }
+}
+
 /**
  * Public boundary: run the repair pipeline.
  *
@@ -226,15 +257,15 @@ export async function runRepair({
       duration_ms: Date.now() - t0,
     });
   }
-  if (!['hooks', 'locks', 'index', 'all'].includes(scope)) {
+  if (!['hooks', 'locks', 'index', 'format', 'all'].includes(scope)) {
     return errorResult({
       category: ERROR_CATEGORIES.SCHEMA,
-      errors: [`invalid scope: ${scope}; expected 'hooks' | 'locks' | 'index' | 'all'`],
+      errors: [`invalid scope: ${scope}; expected 'hooks' | 'locks' | 'index' | 'format' | 'all'`],
       duration_ms: Date.now() - t0,
     });
   }
 
-  const scopes = scope === 'all' ? ['hooks', 'locks', 'index'] : [scope];
+  const scopes = scope === 'all' ? ['hooks', 'locks', 'index', 'format'] : [scope];
   const repairs = [];
   let errors = 0;
   for (const s of scopes) {
@@ -251,6 +282,11 @@ export async function runRepair({
       const r = await repairIndex({ projectRoot, userDir, reindexer });
       if (r.error) errors += 1;
       repairs.push(r);
+    } else if (s === 'format') {
+      // eslint-disable-next-line no-await-in-loop
+      const r = await repairMemoryFormat({ projectRoot });
+      if (r.error) errors += 1;
+      repairs.push(r);
     }
   }
   return {

package/src/result-shapes.mjs

@@ -110,6 +110,14 @@ export const ERROR_CATEGORIES = Object.freeze({
   // NO silent fallback to keyword — the user asked for semantic,
   // and the surface should fail-loud so they know what's missing.
   SEMANTIC_UNAVAILABLE: 'semantic_unavailable',
+
+  // A per-agent config file (Task 50, cross-agent install) could not be
+  // PARSED — it exists but its bytes aren't valid for the declared format
+  // (corrupt/hand-edited JSON, etc.). `mutateAgentConfig` returns this
+  // and REFUSES to write, so a malformed third-party config is never
+  // clobbered (the claude-mem rigor-drift bug class, inverted into a
+  // guarantee — design: cross-agent adapter seam note 2026-06-20 / D-180).
+  CONFIG_PARSE: 'config_parse',
 });
 
 export const ACTION_TYPES = Object.freeze({

package/src/review-queue.mjs

@@ -166,6 +166,9 @@ function serializeReviewQueue({ preamble, entries }) {
   const lines = [...preamble];
   for (const e of entries) {
     lines.push(`## ${e.ts} — auto-extract (medium-trust, pending review)`);
+    lines.push(''); // blank line below the heading (MD022). SAFE: parseReviewQueue
+    // scans i+1..i+5 for the bullet, so a blank heading→bullet gap is tolerated;
+    // the provenance stays at bulletLine+1 (the pair is never split).
     lines.push(`- (${e.id}) ${e.text}`);
     if (e.provenance) lines.push(e.provenance);
     lines.push('');

package/src/scratchpad.mjs

@@ -215,7 +215,13 @@ export function ensureSectionExists(scratchpadPath, sectionTitle) {
   // No leading blank lines for an empty/whitespace-only file (the scaffolded
   // scratchpads are never empty, but keep the output clean if one ever is).
   const prefix = body ? `${body}\n\n` : '';
-  writeFileSync(scratchpadPath, `${prefix}## ${sectionTitle}\n`, 'utf8');
+  // Blank line AFTER the heading too (MD022 blanks-around-headings) — the first
+  // bullet appended into this section then lands after the blank, so the
+  // committed scratchpad is lint-clean. SAFE for readers: findSectionRange uses
+  // a whole-line trim-compare + insertIntoSection skips trailing blanks, so a
+  // blank under the heading doesn't change where bullets insert. The blank is
+  // between the HEADING and the bullet — never inside the bullet↔comment pair.
+  writeFileSync(scratchpadPath, `${prefix}## ${sectionTitle}\n\n`, 'utf8');
   return { created: true };
 }
 
@@ -271,7 +277,11 @@ function archiveEvictedBullets({ tierRoot, tier, scratchpad, evicted, now }) {
   const archivePath = join(archiveDir, 'evicted-bullets.md');
   const ts = now ?? nowIso();
   const header = existsSync(archivePath) ? '' : EVICTED_ARCHIVE_HEADER;
-  const block = `## Evicted ${ts} — consolidate(${scratchpad})\n${evicted
+  // Blank line after the heading so the archive is lint-clean markdown (MD022
+  // blanks-around-headings) — generated memory passes a strict linter by
+  // construction. The preceding header (or the prior block's trailing `\n\n`)
+  // supplies the blank line above.
+  const block = `## Evicted ${ts} — consolidate(${scratchpad})\n\n${evicted
     .map((e) => e.block)
     .join('\n')}\n\n`;
   appendFileSync(archivePath, header + block, 'utf8');

package/src/search.mjs

@@ -481,12 +481,19 @@ function runDecisionsKeywordSearch(_db, opts) {
     // The line offset of the marker = source_line drill-back into DECISIONS.md.
     const sourceLine = content.slice(0, start).split('\n').length;
     // Retracted-tag detection mirrors the WRITER's contract: the tag sits on its
-    // own line DIRECTLY after the `### ` heading (decisions-journal.mjs §2), so
-    // scope the check there — NOT a raw-block substring, which would mislabel an
-    // active entry whose Why merely MENTIONS "_(retracted" (skill-review I1).
-    const headingIdx = block.indexOf('### ');
+    // own line DIRECTLY after the `## ` heading (decisions-journal.mjs §2 —
+    // buildDecisionEntry emits `## ` h2 entries; the retract inserter puts the
+    // tag at headingEnd+1), so scope the check there — NOT a raw-block substring,
+    // which would mislabel an active entry whose Why merely MENTIONS "_(retracted"
+    // (skill-review I1). Match the heading line-start (`\n## `) so body text
+    // containing `##` can't be mistaken for the heading. (Was `### ` — a
+    // pre-existing bug: the writer emits `## `, so this never matched and EVERY
+    // decision read `retracted:false` — Task 164.3.)
+    // The heading is a line-start `## ` (the block opens with the marker comment,
+    // so the heading is never at block offset 0 — match `\n## `).
+    const headingNl = block.indexOf('\n## ');
     const afterHeading =
-      headingIdx === -1 ? '' : block.slice(block.indexOf('\n', headingIdx) + 1);
+      headingNl === -1 ? '' : block.slice(block.indexOf('\n', headingNl + 1) + 1);
     const retracted = afterHeading.startsWith('_(retracted');
     hits.push({
       id: markers[i].id,

package/src/semantic-backend.mjs

@@ -28,7 +28,7 @@
 // ≤1500-char chunking rule is satisfied by construction).
 
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
+import { parseJsonFile } from './read-json.mjs';
 import { join } from 'node:path';
 
 // The D-105 ladder's WINNER (bake-off 2026-06-10, bench:recall on the Task-99
@@ -383,14 +383,12 @@ const VALID_DEFAULT_MODES = new Set(['keyword', 'semantic', 'hybrid']);
  * default — no surprise model downloads on machines that never opted in).
  */
 export function resolveDefaultSearchMode({ projectRoot }) {
-  try {
-    const p = join(projectRoot, 'context', 'settings.json');
-    if (!existsSync(p)) return 'keyword';
-    const mode = JSON.parse(readFileSync(p, 'utf8'))?.search?.default_mode;
-    return VALID_DEFAULT_MODES.has(mode) ? mode : 'keyword';
-  } catch {
-    return 'keyword';
-  }
+  // BOM-tolerant (parseJsonFile): a Windows-editor BOM on context/settings.json
+  // must not silently downgrade a `hybrid` user to keyword (D-187). Missing or
+  // malformed → keyword.
+  const p = join(projectRoot, 'context', 'settings.json');
+  const mode = parseJsonFile(p, { fallback: null })?.search?.default_mode;
+  return VALID_DEFAULT_MODES.has(mode) ? mode : 'keyword';
 }
 
 /**

package/src/settings-hooks.mjs

@@ -57,6 +57,8 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { stripBom } from './read-json.mjs';
+import { MCP_AUTO_APPROVE } from './kiro-constants.mjs';
 
 /**
  * Canonical npm-route hooks block. Shell form (no `args`), PATH-resolved
@@ -64,6 +66,24 @@ import { dirname, join } from 'node:path';
  * (modulo command form) plugin/hooks/hooks.json.
  */
 export const KIT_HOOKS_BLOCK = Object.freeze({
+  // PermissionRequest — the prompt-free auto-approver (Task 172, the v0.4.1
+  // cut-gate fix). Fires when Claude Code is about to show a permission dialog
+  // for one of the kit's OWN surfaces and answers "allow" so capture/recall stay
+  // seamless. Two matchers: the kit's MCP tools (`mcp__cmk__.*`) and the Skill
+  // tool (the "Use skill?" prompt). The handler (cmk-approve-permission)
+  // self-checks the tool name and approves ONLY kit tools/skills — the matcher
+  // is the first narrowing, the handler's check is the second (defence in depth).
+  // Needed because CC 2.1.x stopped honouring `permissions.allow` MCP rules +
+  // skill `allowed-tools` for these prompts (anthropics/claude-code#17499,
+  // #18837→#14956); the PermissionRequest hook is the documented, working path.
+  PermissionRequest: [
+    { matcher: 'mcp__cmk__.*', hooks: [{ type: 'command', command: 'cmk-approve-permission', timeout: 5 }] },
+    { matcher: 'Skill', hooks: [{ type: 'command', command: 'cmk-approve-permission', timeout: 5 }] },
+  ],
+  // PreToolUse — the memory delete-guardrail (D-192). Blocks a destructive
+  // shell command (rm / Remove-Item / git clean …) aimed at a memory path
+  // BEFORE it runs. The only kit hook that can exit non-zero (2 = block).
+  PreToolUse: [{ matcher: 'Bash|PowerShell', hooks: [{ type: 'command', command: 'cmk-guard-memory', timeout: 5 }] }],
   SessionStart: [{ hooks: [{ type: 'command', command: 'cmk-inject-context', timeout: 30 }] }],
   UserPromptSubmit: [{ hooks: [{ type: 'command', command: 'cmk-capture-prompt', timeout: 10 }] }],
   PostToolUse: [{ matcher: 'Write|Edit|MultiEdit', hooks: [{ type: 'command', command: 'cmk-observe-edit', async: true, timeout: 120 }] }],
@@ -81,6 +101,8 @@ export const KIT_HOOKS_BLOCK = Object.freeze({
  */
 export const KIT_COMMAND_TOKENS = Object.freeze([
   'cmk-version-check',
+  'cmk-approve-permission',
+  'cmk-guard-memory',
   'cmk-inject-context',
   'cmk-capture-prompt',
   'cmk-observe-edit',
@@ -122,7 +144,9 @@ export function writeKitHooks(settingsPath) {
   let settings = {};
   if (existsSync(settingsPath)) {
     try {
-      settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+      // stripBom: a Windows-editor BOM must not make a valid settings.json read
+      // as corrupt and block hook wiring (D-187). Real corruption still errors.
+      settings = JSON.parse(stripBom(readFileSync(settingsPath, 'utf8')));
     } catch (err) {
       return {
         changed: false,
@@ -204,7 +228,33 @@ export function writeKitHooks(settingsPath) {
   // Task 133: memory-search joins memory-write — every scaffolded skill needs
   // its own allow entry or the model's invocation trips a "Use skill?" prompt
   // (the Task-90 class; 75.1 scaffolded the skill but missed this).
-  const KIT_ALLOW = ['Bash(cmk:*)', 'Skill(memory-write)', 'Skill(memory-search)', 'mcp__cmk__*'];
+  // Task 169 (the v0.4.1 cut-gate find, 2026-06-26): Claude Code 2.1.x changed
+  // skill-permission matching — the bare `Skill(memory-write)` rule alone no
+  // longer suppressed the "Use skill?" prompt; when the user clicked "allow for
+  // this project", Claude Code wrote BOTH `Skill(memory-write)` AND
+  // `Skill(memory-write:*)` into settings.local.json. So the kit emits BOTH forms
+  // (bare for older CC, `:*` for 2.1.x+) — pending a docs re-verification of the
+  // current skill-permission syntax.
+  // Task 171 (v0.4.1 cut-gate ground-truth, 2026-06-26): the `mcp__cmk__*` server
+  // WILDCARD no longer suppresses the per-tool approval prompt on Claude Code
+  // 2.1.x — a DIRECT `mk_remember` call (the model using the MCP tool outside the
+  // skill's own `allowed-tools`) prompts "Do you want to proceed with
+  // mcp__cmk__mk_remember?", and CC writes the SPECIFIC tool name when allowed.
+  // (CC 2.1.x churned permission matching heavily — multiple changelog entries
+  // closed wildcard auto-approve holes, e.g. 2.1.145 "permission-prompt bypass".)
+  // The wildcard worked on older CC; it doesn't now. So allow-list each SPECIFIC
+  // cmk MCP tool (the canonical 11 in MCP_AUTO_APPROVE — shared with the Kiro
+  // pre-trust) AND keep `mcp__cmk__*` (harmless + future-proof). This is the same
+  // upstream-format-tracking the kit does for the Skill rule (D-209) and Kiro.
+  const KIT_ALLOW = [
+    'Bash(cmk:*)',
+    'Skill(memory-write)',
+    'Skill(memory-write:*)',
+    'Skill(memory-search)',
+    'Skill(memory-search:*)',
+    'mcp__cmk__*',
+    ...MCP_AUTO_APPROVE.map((tool) => `mcp__cmk__${tool}`),
+  ];
   if (!settings.permissions || typeof settings.permissions !== 'object') {
     settings.permissions = {};
   }
@@ -217,6 +267,21 @@ export function writeKitHooks(settingsPath) {
     }
   }
 
+  // Task 172: pre-approve the kit's OWN project-scoped `.mcp.json` server so its
+  // tools connect without the per-project "approve this MCP server?" prompt.
+  // `enabledMcpjsonServers` names specific servers to approve (NOT
+  // `enableAllProjectMcpServers`, which would blanket-approve EVERY server in
+  // `.mcp.json` — too broad for a kit shipped to others; we vouch only for our
+  // own server). This clears the SERVER-approval gate; the PermissionRequest
+  // hook above clears the per-TOOL gate. Idempotent + preserves any servers the
+  // user already approved.
+  if (!Array.isArray(settings.enabledMcpjsonServers)) {
+    settings.enabledMcpjsonServers = [];
+  }
+  if (!settings.enabledMcpjsonServers.includes('cmk')) {
+    settings.enabledMcpjsonServers.push('cmk');
+  }
+
   const after = JSON.stringify(settings);
   const changed = before !== after;
 
@@ -250,7 +315,9 @@ export function writeKitMcpServer(projectRoot) {
   let config = {};
   if (existsSync(mcpPath)) {
     try {
-      config = JSON.parse(readFileSync(mcpPath, 'utf8'));
+      // stripBom: a BOM'd .mcp.json must not read as corrupt and block MCP
+      // registration (D-187). Real corruption still errors.
+      config = JSON.parse(stripBom(readFileSync(mcpPath, 'utf8')));
     } catch (err) {
       return { changed: false, path: mcpPath, error: `${mcpPath} parse error: ${err?.message ?? err}` };
     }