@lh8ppl/claude-memory-kit 0.3.5 → 0.4.0

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,7 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { stripBom } from './read-json.mjs';
 
 /**
  * Canonical npm-route hooks block. Shell form (no `args`), PATH-resolved
@@ -64,6 +65,10 @@ import { dirname, join } from 'node:path';
  * (modulo command form) plugin/hooks/hooks.json.
  */
 export const KIT_HOOKS_BLOCK = Object.freeze({
+  // 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 +86,7 @@ export const KIT_HOOKS_BLOCK = Object.freeze({
  */
 export const KIT_COMMAND_TOKENS = Object.freeze([
   'cmk-version-check',
+  'cmk-guard-memory',
   'cmk-inject-context',
   'cmk-capture-prompt',
   'cmk-observe-edit',
@@ -122,7 +128,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,
@@ -250,7 +258,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}` };
     }