@lh8ppl/claude-memory-kit 0.3.5 → 0.4.1

package/src/agent-profiles.mjs

@@ -0,0 +1,118 @@
+// agent-profiles.mjs — the per-agent profile REGISTRY (Task 50.C/50.E).
+//
+// Each agent is a pure-DATA profile built via defineAgentProfile (the D-180
+// "data, not classes" seam). The kit's core (store / compression / search / CLI
+// / MCP server) is identical across agents; only these declarations differ.
+//
+// Scope discipline (D-180): a plain object keyed by name, NOT a registry
+// framework — single-digit agent count; opencode's data-row registry pays off
+// at N≈75, premature here. Adding an agent in a later version = one more entry.
+//
+// Public surface:
+//   AGENT_PROFILES — frozen map { name → frozen descriptor }
+//   getAgentProfile(name) → descriptor | undefined
+//   listAgentProfiles() → descriptor[]
+
+import { defineAgentProfile } from './agent-profile.mjs';
+
+// ── Claude Code ──────────────────────────────────────────────────────────────
+// The reference profile. Declares the SAME legs install.mjs wires today (the
+// KIT_HOOKS_BLOCK in settings-hooks.mjs + the `cmk` MCP server in .mcp.json),
+// expressed as data. install.mjs keeps using its existing Claude-Code path for
+// v0.4.0 (regression-proof); this profile is the canonical declaration the
+// routing (50.F) dispatches on and the parity validator (50.D) checks.
+const claudeCode = defineAgentProfile({
+  name: 'claude-code',
+  displayName: 'Claude Code',
+  integrationType: 'native-hooks-mcp',
+  detect: { command: 'claude' },
+  // Claude Code's instruction surface is the managed block in CLAUDE.md.
+  instructionFile: 'CLAUDE.md',
+  mcp: { path: '.mcp.json', serversKey: 'mcpServers' },
+  hooks: {
+    mechanism: 'settings-json', // <projectRoot>/.claude/settings.json hooks[] entries
+    path: '.claude/settings.json',
+    // abstract lifecycle event → Claude Code's event name (here they coincide).
+    eventMap: {
+      sessionStart: 'SessionStart',
+      promptSubmit: 'UserPromptSubmit',
+      postEdit: 'PostToolUse',
+      turnEnd: 'Stop',
+      sessionEnd: 'SessionEnd',
+    },
+  },
+  // Claude Code transcripts: ~/.claude/projects/<slug>/<session>.jsonl (JSONL).
+  transcript: { dir: '~/.claude/projects', workspaceKey: 'slug', parse: 'jsonl' },
+});
+
+// ── Kiro (Task 50.E) ─────────────────────────────────────────────────────────
+// Primary-verified against kiro.dev + a real install (D-180). VS Code fork.
+// Kiro wires BOTH hook surfaces (Task 50.N — full Claude-Code parity):
+//   • CLI agent-config (.kiro/agents/cmk.json "hooks") — the eventMap below;
+//   • IDE Agent-Hooks (.kiro/hooks/*.json v1 + legacy .kiro.hook) — kiro-ide-hooks.mjs.
+// Both drive the SAME `cmk hook <event>` dispatcher → the same inject/capture/
+// observe/guard cores; only the per-surface trigger names differ (CLI camelCase
+// vs IDE v1 PascalCase). All four legs (inject/capture/observe-edit/delete-guard)
+// are wired on both surfaces as of 50.N.1–50.N.3.
+const kiro = defineAgentProfile({
+  name: 'kiro',
+  displayName: 'Kiro',
+  integrationType: 'native-hooks-mcp',
+  detect: { homeDir: '.kiro' },
+  // Steering file with `inclusion: always` frontmatter (applied at write time).
+  instructionFile: '.kiro/steering/claude-memory-kit.md',
+  mcp: { path: '.kiro/settings/mcp.json', serversKey: 'mcpServers' },
+  hooks: {
+    mechanism: 'agent-config-json', // .kiro/agents/<name>.json "hooks" object (CLI)
+    path: '.kiro/agents/cmk.json',
+    // The CLI agent-config trigger names. The IDE v1 surface uses PascalCase
+    // equivalents (UserPromptSubmit/Stop/PostToolUse/PreToolUse) — see
+    // kiro-ide-hooks.mjs. postEdit→postToolUse + the delete-guard (preToolUse)
+    // are both wired (50.N.2/50.N.3).
+    eventMap: {
+      sessionStart: 'agentSpawn',
+      promptSubmit: 'userPromptSubmit',
+      postEdit: 'postToolUse',
+      turnEnd: 'stop',
+    },
+  },
+  // Transcript — TWO schemas (D-200), resolved at capture time by readKiroTurn:
+  //   • IDE: per-session JSON under globalStorage, base64url(workspacePath), a
+  //     `history[]` array (the dir/key/parse below);
+  //   • kiro-CLI: ~/.kiro/sessions/cli/<uuid>.json, matched by `cwd`, a
+  //     `session_state.conversation_metadata.user_turn_metadatas[]` shape (the
+  //     fallback path — readKiroCliTurn). The fields here describe the IDE shape;
+  //     the CLI shape is handled by the readKiroTurn fallback, not a profile field.
+  transcript: {
+    dir: 'globalStorage/kiro.kiroagent/workspace-sessions',
+    workspaceKey: 'base64url',
+    parse: 'json-history',
+  },
+});
+
+// ── AGENTS.md (Task 50.G — the instruction-only breadth rung) ────────────────
+// The cheap multi-tool reach: emit a managed block in AGENTS.md (the cross-tool
+// instruction-file convention several non-Claude agents read — Cursor, Zed,
+// Codex, gemini-cli, …). NO hooks, NO MCP — instruction surface only. For tools
+// we haven't built a full adapter for; a thin rung, not the depth play. (D-180 §5.)
+const agentsmd = defineAgentProfile({
+  name: 'agents-md',
+  displayName: 'AGENTS.md',
+  integrationType: 'instruction-only',
+  detect: { always: true }, // any repo can carry an AGENTS.md
+  instructionFile: 'AGENTS.md',
+});
+
+export const AGENT_PROFILES = Object.freeze({
+  'claude-code': claudeCode,
+  kiro,
+  'agents-md': agentsmd,
+});
+
+export function getAgentProfile(name) {
+  return AGENT_PROFILES[name];
+}
+
+export function listAgentProfiles() {
+  return Object.values(AGENT_PROFILES);
+}

package/src/approve-permission.mjs

@@ -0,0 +1,92 @@
+// PermissionRequest auto-approve logic — the prompt-free fix (Task 172).
+//
+// Background (the v0.4.1 cut-gate, 2026-06-27). Claude Code 2.1.x tightened
+// permission matching so that neither the kit's `permissions.allow` MCP rules
+// (`mcp__cmk__*` + the specific names, Task 171) NOR a skill's `allowed-tools`
+// grant reliably suppress the per-tool MCP approval prompt or the "Use skill?"
+// prompt — see anthropics/claude-code#17499 (allowed-tools for MCP tools is
+// undocumented/unreliable) and #18837 → #14956 (allowed-tools not enforced).
+// The popup is a CLAUDE CODE change, not a kit regression: the skill + allow-list
+// config has been byte-stable since Task 108/117.
+//
+// The DOCUMENTED, working mechanism is a `PermissionRequest` hook
+// (code.claude.com/docs/en/hooks-guide#auto-approve-specific-permission-prompts):
+// it fires when CC is about to show a permission dialog, and a hook that writes
+// `{"behavior":"allow"}` answers it on the user's behalf — proven live (v041l):
+// the dialog flashes then auto-dismisses, the tool runs, no click required.
+//
+// This module decides — given the hook payload — whether to auto-approve. It
+// approves ONLY the kit's OWN surfaces (its MCP tools + its scaffolded skills),
+// never anything else. Two-layer safety: the wired matcher is already narrow
+// (`mcp__cmk__.*` / `Skill`), and this self-check is the second layer, so even a
+// loose matcher can't make the hook approve a non-kit tool. Returns `null` for
+// anything not kit-owned → the hook stays silent → CC's normal permission flow
+// runs unchanged.
+
+// The kit's own scaffolded skills (template/.claude/skills/<name>). Keep in sync
+// with the Skill(...) entries in settings-hooks.mjs KIT_ALLOW.
+const KIT_SKILLS = Object.freeze(['memory-write', 'memory-search']);
+
+// The allow decision shape CC expects on stdout for a PermissionRequest hook.
+export const ALLOW_DECISION = Object.freeze({
+  hookSpecificOutput: {
+    hookEventName: 'PermissionRequest',
+    decision: { behavior: 'allow' },
+  },
+});
+
+/**
+ * True iff `toolName` is one of the kit's own MCP tools (any `mcp__cmk__<tool>`).
+ */
+function isKitMcpTool(toolName) {
+  return typeof toolName === 'string' && toolName.startsWith('mcp__cmk__');
+}
+
+/**
+ * True iff this is an invocation of one of the kit's own scaffolded skills.
+ * The Skill tool surfaces the skill name either as the tool name's suffix
+ * (`Skill(memory-write)`) or in `tool_input.name`/`tool_input.skill` — accept
+ * either shape so a CC payload-format change doesn't silently stop matching.
+ *
+ * Security boundary: the `tool_input.name`/`skill` fallback is consulted ONLY
+ * when `tool_name` identifies the Skill tool (`Skill` or `Skill(...)`). Without
+ * that gate, a non-Skill request whose `tool_input` merely happened to carry
+ * `{name:"memory-write"}` (e.g. a `Bash` call) would match — defeating the
+ * second layer of defence-in-depth (the matcher is the first). We never read
+ * `tool_input` for a tool that isn't the Skill tool.
+ */
+function isKitSkill(toolName, toolInput) {
+  if (typeof toolName !== 'string') return false;
+  // The documented tool-name form for a skill invocation: `Skill(<name>)`.
+  for (const skill of KIT_SKILLS) {
+    if (toolName === `Skill(${skill})`) return true;
+  }
+  // Only trust the tool_input name shape for an actual Skill-tool request.
+  // (A bare `tool_name === "<skill>"` is NOT matched — it isn't a documented
+  // CC shape and would risk approving any unrelated tool that happened to share
+  // the name.)
+  if (toolName === 'Skill' || toolName.startsWith('Skill(')) {
+    const named = toolInput && (toolInput.name ?? toolInput.skill ?? toolInput.skillName);
+    if (typeof named === 'string' && KIT_SKILLS.includes(named)) return true;
+  }
+  return false;
+}
+
+/**
+ * Decide whether to auto-approve a PermissionRequest for a kit-owned surface.
+ *
+ * @param {object} payload - the hook payload from stdin
+ *   ({ tool_name, tool_input, ... }).
+ * @returns {object|null} the ALLOW_DECISION object to print on stdout, or null
+ *   when the request is NOT for a kit surface (the hook emits nothing → CC's
+ *   normal permission flow proceeds).
+ */
+export function evaluatePermissionRequest(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  const toolName = payload.tool_name;
+  const toolInput = payload.tool_input;
+  if (isKitMcpTool(toolName) || isKitSkill(toolName, toolInput)) {
+    return ALLOW_DECISION;
+  }
+  return null;
+}

package/src/auto-extract.mjs

@@ -858,18 +858,25 @@ export async function runAutoExtract({
         // ceiling is free. Live-test finding (2026-06-01, live-test-4 baseline).
         timeoutMs: 90_000,
       });
-      // Touch the cooldown marker IMMEDIATELY after the Haiku call
-      // resolves — this is the "we spent the budget" signal that
-      // compress-session.mjs reads to skip its own Haiku call within
-      // 120s of ours. Touching on success only (not in the catch below)
-      // would mean a failing Haiku in the auto-extract path doesn't
-      // block compress-session — which would then re-spend the budget
-      // on the failure. The catch path below also touches.
+      // Touch the cooldown marker after a SUCCESSFUL Haiku call — the
+      // "we spent the budget" signal compress-session.mjs reads to skip its
+      // own Haiku call within 120s of ours.
+      //
+      // **Original behavior (pre-Task-167, preserved as decision-trail):** the
+      // catch block below ALSO touched the cooldown ("spent the budget,
+      // succeeded OR failed"), so a failing Haiku here blocked compress-session
+      // for 120s — on the theory that a failure shouldn't let the next caller
+      // re-spend the budget on the same broken call.
+      // **Task 167.F change (D-207, Q5):** the cooldown now fires on SUCCESS
+      // ONLY. A FAILED call did NOT successfully spend the budget — blocking the
+      // next NEEDED compress for 120s after a *transient* failure is the wrong
+      // gate (it was the SECONDARY cause of the 410 KB now.md bloat: after the
+      // dead cron, failed-call cooldowns kept the roll skipped). Correctness >
+      // cost — a transient failure must be free to retry.
       touchCooldownMarker({ projectRoot, now: ts });
     } catch (err) {
-      // Spent the Haiku budget (succeeded OR failed); touch the
-      // cooldown so compress-session skips within 120s.
-      touchCooldownMarker({ projectRoot, now: ts });
+      // Task 167.F: do NOT touch the cooldown on failure (see the success-path
+      // comment above) — a failed call must not block the next compress's retry.
       // Route on the error TYPE — distinguishes "took too long"
       // (HAIKU_TIMEOUT) from "subprocess exited non-zero"
       // (HAIKU_FAILED). Using `instanceof HaikuTimeoutError`

package/src/auto-persona.mjs

@@ -336,12 +336,16 @@ export async function autoPersona(opts = {}) {
       // ceiling, so it passes a generous value — the explicit command can wait.
       timeoutMs,
     });
-    // Spent a Haiku call — refresh the shared cooldown marker so the next
-    // gated caller backs off. (touch even on cooldownMs:0 cycles: the call
+    // Spent a Haiku call SUCCESSFULLY — refresh the shared cooldown marker so the
+    // next gated caller backs off. (touch even on cooldownMs:0 cycles: the call
     // happened, so the marker should reflect it for any LATER gated caller.)
     touchCooldownMarker({ projectRoot, now: ts });
   } catch (err) {
-    touchCooldownMarker({ projectRoot, now: ts });
+    // Task 167.F (D-207, Q5): do NOT touch the cooldown on FAILURE — a failed
+    // Haiku call did not successfully spend the budget, and blocking the next
+    // needed compress for 120s after a transient failure is the wrong gate
+    // (correctness > cost; a transient failure must be free to retry). Original
+    // pre-167 behavior touched here too; preserved as decision-trail.
     return errorResult({
       category: ERROR_CATEGORIES.COMPRESS_FAILED,
       errors: [err?.message ?? String(err)],
@@ -421,7 +425,10 @@ export function appendPersonaReviewQueue({ userDir, entries, now }) {
   if (blocks.length === 0) return queuePath;
 
   const header = `## ${ts} — persona-synthesis (pending review)`;
-  appendFileSync(queuePath, `${header}\n${blocks.join('\n')}\n\n`, 'utf8');
+  // Blank line below the heading (MD022). SAFE: parsePersonaReviewQueue keys on
+  // the bullet line + its i+1 meta-comment, not on heading adjacency; the blank
+  // is between heading and the first bullet, never inside the bullet↔comment pair.
+  appendFileSync(queuePath, `${header}\n\n${blocks.join('\n')}\n\n`, 'utf8');
   return queuePath;
 }
 

package/src/compaction-state.mjs

@@ -0,0 +1,204 @@
+// Compaction-state deep module (Task 167, D-206/D-207).
+//
+// Owns the single question "does memory need compacting right now, and is the
+// scheduled cron alive?" — replacing the old detectStaleness gating that
+// short-circuited to 'cron-active' on the mere EXISTENCE of a cron-registered
+// sentinel (so a registered-but-dead cron disabled the lazy roll and now.md grew
+// unbounded — the v0.4.0 dogfood's 410 KB freeze).
+//
+// Two public methods (the deep interface — Q3):
+//
+//   isCompactionNeeded({projectRoot, now, dailyTtlMs?, weeklyTtlMs?})
+//     → {verdict, cronStale, heartbeatAge}
+//        verdict: 'fresh' | 'stale-now' | 'stale-daily' | 'stale-weekly'
+//               | 'cron-active' | 'no-context-dir'
+//        cronStale: boolean   — a cron IS registered but its heartbeat is stale
+//        heartbeatAge: number|null — ms since the last cron run, null if no cron
+//
+//   recordCronHeartbeat({projectRoot, now})  — the ONLY writer; the cron bins
+//     (cmk-daily-distill / cmk-weekly-curate) call it on each fire so the gate
+//     keys off "a run HAPPENED recently" (age), not "a scheduler is registered"
+//     (existence). The anacron model — see docs/research/2026-06-25-cron-liveness.
+//
+// Marker-vs-derive = HYBRID (Q2; the GNU make "Empty Target Files" rule): the
+// now/daily/weekly verdicts are DERIVED from the artifacts the work already
+// rewrites (now.md content, recent.md mtime, today-*.md dates — no new marker,
+// ADR-0002); only cron-liveness gets a stamp, because no artifact expresses "is
+// the background scheduler alive".
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const DEFAULT_DAILY_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+export const DEFAULT_WEEKLY_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+// The cron heartbeat is considered alive within ~2× the daily cron interval
+// (the anacron model: a registered cron that hasn't run in 2 days is dead — the
+// machine was asleep, the registration silently failed, etc.). 2× the 24h daily
+// cadence gives one full grace period before the lazy roll takes over.
+export const DEFAULT_HEARTBEAT_TTL_MS = 2 * DEFAULT_DAILY_TTL_MS; // 48 hours
+
+const SESSIONS_REL = ['context', 'sessions'];
+const NOW_MD_REL = ['context', 'sessions', 'now.md'];
+const RECENT_MD_REL = ['context', 'sessions', 'recent.md'];
+const HEARTBEAT_REL = ['context', '.locks', 'cron-heartbeat'];
+
+const TODAY_RE = /^today-(\d{4}-\d{2}-\d{2})\.md$/;
+
+/**
+ * Path to the cron-heartbeat stamp. Public so register-crons.mjs + the cron bins
+ * can write it without re-deriving the path.
+ */
+export function cronHeartbeatPath(projectRoot) {
+  return join(projectRoot, ...HEARTBEAT_REL);
+}
+
+/**
+ * Record that the scheduled cron actually RAN (the anacron stamp). The ONLY
+ * writer of the heartbeat — called by the cron bins on each fire (success OR
+ * benign no-op; "ran and did nothing" still proves the cron is alive). Best-effort
+ * + atomic-enough (mkdir then touch); mtime is the load-bearing signal.
+ */
+export function recordCronHeartbeat({ projectRoot, now }) {
+  if (!projectRoot) return;
+  const marker = cronHeartbeatPath(projectRoot);
+  mkdirSync(dirname(marker), { recursive: true });
+  if (!existsSync(marker)) {
+    writeFileSync(marker, '', 'utf8');
+  }
+  const ts = new Date(now ?? Date.now());
+  try {
+    utimesSync(marker, ts, ts);
+  } catch {
+    // utimes can fail on exotic filesystems; existence + a write timestamp are
+    // the load-bearing signal, and writeFileSync already stamped it on create.
+  }
+}
+
+/** ms since the cron last ran, or null if no cron heartbeat exists. */
+function heartbeatAgeMs(projectRoot, nowMs) {
+  const marker = cronHeartbeatPath(projectRoot);
+  if (!existsSync(marker)) return null;
+  try {
+    return nowMs - statSync(marker).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function nowMdHasContent(projectRoot) {
+  const p = join(projectRoot, ...NOW_MD_REL);
+  if (!existsSync(p)) return false;
+  try {
+    return readFileSync(p, 'utf8').trim() !== '';
+  } catch {
+    return false;
+  }
+}
+
+function recentMdMtimeMs(projectRoot) {
+  const p = join(projectRoot, ...RECENT_MD_REL);
+  if (!existsSync(p)) return null;
+  try {
+    return statSync(p).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function listTodayFiles(projectRoot) {
+  const sessionsDir = join(projectRoot, ...SESSIONS_REL);
+  if (!existsSync(sessionsDir)) return [];
+  const matches = [];
+  for (const name of readdirSync(sessionsDir)) {
+    const m = TODAY_RE.exec(name);
+    if (!m) continue;
+    matches.push({ name, date: m[1], path: join(sessionsDir, name) });
+  }
+  return matches;
+}
+
+/**
+ * The deep read: does memory need compacting, and is the cron alive?
+ *
+ * Verdict precedence (Q2): no-context-dir > stale-now > cron-active(fresh) >
+ * stale-weekly > stale-daily > fresh. Note 'cron-active' NO LONGER short-circuits
+ * above the bloat check — a stale-now (un-rolled prior-session content) ALWAYS
+ * wins, because correctness > deferring to a possibly-dead cron ("we're in the
+ * memory business", Q4). Only a FRESH cron defers the derived daily/weekly work.
+ */
+export function isCompactionNeeded({
+  projectRoot,
+  now,
+  dailyTtlMs = DEFAULT_DAILY_TTL_MS,
+  weeklyTtlMs = DEFAULT_WEEKLY_TTL_MS,
+  heartbeatTtlMs = DEFAULT_HEARTBEAT_TTL_MS,
+} = {}) {
+  const nowMs = new Date(now ?? Date.now()).getTime();
+
+  if (!projectRoot) {
+    return { verdict: 'no-context-dir', reason: 'missing-project-root', cronStale: false, heartbeatAge: null };
+  }
+
+  // Cron liveness — by AGE, never existence (the 167.A fix). A registered cron
+  // whose heartbeat is older than the TTL is DEAD; treat it as no cron so the
+  // lazy roll takes over.
+  const hbAge = heartbeatAgeMs(projectRoot, nowMs);
+  const cronRegistered = hbAge !== null;
+  const cronAlive = cronRegistered && hbAge < heartbeatTtlMs;
+  const cronStale = cronRegistered && !cronAlive;
+
+  const base = { cronStale, heartbeatAge: hbAge };
+
+  const sessionsDir = join(projectRoot, ...SESSIONS_REL);
+  if (!existsSync(sessionsDir)) {
+    return { verdict: 'no-context-dir', reason: 'sessions-dir-missing', ...base };
+  }
+
+  // stale-now wins over cron-active (Q4): un-rolled now.md content must drain
+  // THIS session regardless of whether a (possibly dead, possibly alive) cron is
+  // registered — the correctness-over-deferral rule.
+  if (nowMdHasContent(projectRoot)) {
+    return { verdict: 'stale-now', reason: 'now-md-has-prior-session-content', ...base };
+  }
+
+  // A LIVE cron owns the remaining (daily/weekly) levels — defer to it.
+  if (cronAlive) {
+    return { verdict: 'cron-active', reason: 'cron-heartbeat-fresh', ...base };
+  }
+
+  const files = listTodayFiles(projectRoot);
+
+  // Weekly: any today-*.md older than weeklyTtlMs by its date stamp.
+  const weeklyCutoffMs = nowMs - weeklyTtlMs;
+  const hasOldToday = files.some((f) => {
+    const fileMs = new Date(f.date + 'T00:00:00Z').getTime();
+    return Number.isFinite(fileMs) && fileMs < weeklyCutoffMs;
+  });
+  if (hasOldToday) {
+    return { verdict: 'stale-weekly', reason: 'today-file-older-than-7d', ...base };
+  }
+
+  // No today files at all → nothing to compress → fresh (Task 36 I1).
+  if (files.length === 0) {
+    return { verdict: 'fresh', reason: 'no-input', ...base };
+  }
+
+  // Daily: recent.md missing OR older than dailyTtlMs.
+  const mtimeMs = recentMdMtimeMs(projectRoot);
+  if (mtimeMs === null) {
+    return { verdict: 'stale-daily', reason: 'recent-md-missing', ...base };
+  }
+  if (nowMs - mtimeMs > dailyTtlMs) {
+    return { verdict: 'stale-daily', reason: 'recent-md-older-than-ttl', ...base };
+  }
+  return { verdict: 'fresh', reason: 'within-ttl', ...base };
+}

package/src/compress-session.mjs

@@ -206,10 +206,22 @@ function restoreRolling(projectRoot, rollingPath) {
 function appendToTodayMd({ projectRoot, date, body }) {
   const path = todayMdPath(projectRoot, date);
   mkdirSync(dirname(path), { recursive: true });
+  // Lint-clean append (MD022 blanks-around-headings): a same-day re-append puts
+  // the new block's leading `## ` heading right after the prior block, with only
+  // the prior block's single trailing `\n` above it → heading not blank-
+  // surrounded. Guarantee exactly one blank line ABOVE the new block when the
+  // file already has content.
+  let prefix = '';
+  if (existsSync(path)) {
+    const existing = readFileSync(path, 'utf8');
+    if (existing.trim() !== '') {
+      prefix = existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+    }
+  }
   // Append with a trailing newline so successive same-day appends
   // don't collide on a missing terminator.
   const suffix = body.endsWith('\n') ? '' : '\n';
-  appendFileSync(path, body + suffix, 'utf8');
+  appendFileSync(path, prefix + body + suffix, 'utf8');
   return path;
 }
 

package/src/config-core.mjs

@@ -21,9 +21,10 @@
 // (observations have their own provenance/shadowed_by surface, §6); this is
 // the concrete settings half the semantic default forced into existence.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { resolveTierRoot } from './tier-paths.mjs';
+import { parseJsonFile } from './read-json.mjs';
 
 // Highest-precedence first.
 const TIERS = Object.freeze([
@@ -47,14 +48,11 @@ function settingsPathFor(tierName, { projectRoot, userDir }) {
 }
 
 function readSettings(path) {
-  if (!existsSync(path)) return null;
-  try {
-    return JSON.parse(readFileSync(path, 'utf8'));
-  } catch {
-    // A malformed settings file is treated as absent for resolution — never
-    // throw on a read (a hand-broken JSON shouldn't crash `cmk config get`).
-    return null;
-  }
+  // BOM-tolerant (parseJsonFile): a settings.json written by a Windows editor
+  // carries a UTF-8 BOM that a bare JSON.parse would reject (D-187). A missing
+  // OR malformed file resolves to null — never throw on a read (a hand-broken
+  // JSON shouldn't crash `cmk config get`).
+  return parseJsonFile(path, { fallback: null });
 }
 
 // Walk a dotted path; returns {found, value}. `found` distinguishes a key

package/src/decisions-journal.mjs

@@ -33,6 +33,7 @@ import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse as parseFrontmatter } from './frontmatter.mjs';
 import { ID_PATTERN } from './tier-paths.mjs';
+import { trimTrailingNewlines } from './managed-block.mjs';
 
 export const DECISIONS_HEADER =
   '# Decisions\n\n' +
@@ -62,9 +63,15 @@ function dateOnly(iso) {
  */
 export function buildDecisionEntry(f) {
   const date = dateOnly(f.createdAt);
+  // Blank lines around the `###` heading so the committed journal is lint-clean
+  // markdown (markdownlint MD022 "blanks-around-headings"). The HTML marker, the
+  // heading, and the When/Why block are each separated by a blank line — the
+  // generated memory passes a strict linter by construction, not by exemption.
   const lines = [
     markerFor(f.id),
-    `### ${f.title}`,
+    '',
+    `## ${f.title}`,
+    '',
     `**When:** ${date} · **Fact:** \`${f.id}\``,
   ];
   if (f.why && String(f.why).trim()) {
@@ -129,8 +136,12 @@ export function updateDecisionsJournal({ existingContent = '', facts = [], tombs
     // from attaching the retraction note to the NEXT entry's heading.
     const nextMarker = content.indexOf('<!-- decision:', idx + marker.length);
     const spanEnd = nextMarker === -1 ? content.length : nextMarker;
-    // Find this entry's heading line (the `### …` after the marker, within span).
-    const headingStart = content.indexOf('### ', idx);
+    // Find this entry's heading line (the `## …` after the marker, within span).
+    // Anchor on a line-start `## ` (newline-prefixed) so body text containing
+    // `##` can't be mistaken for the heading. buildDecisionEntry emits the
+    // heading on its own line right after the marker + a blank line.
+    const headingNl = content.indexOf('\n## ', idx);
+    const headingStart = headingNl === -1 ? -1 : headingNl + 1;
     if (headingStart === -1 || headingStart >= spanEnd) continue;
     const headingEnd = content.indexOf('\n', headingStart);
     if (headingEnd === -1) continue;
@@ -145,6 +156,63 @@ export function updateDecisionsJournal({ existingContent = '', facts = [], tombs
   return content;
 }
 
+/**
+ * Migrate an OLD-format journal (pre-Task-164.1: `### title` headings with no
+ * blank lines around them) to the lint-clean shape buildDecisionEntry now emits
+ * (`## title` with a blank line above + below). Append-only-safe: every entry +
+ * its content is preserved; only the heading level + surrounding blank lines
+ * change. Idempotent (already-clean content returns unchanged) and CRLF-tolerant
+ * (re-emits `\n`). Line-based (no backtracking regex — the ReDoS-safe discipline).
+ *
+ * The retraction tag (`_(retracted …)_`) sits on the line directly under the
+ * heading; it stays there (the blank-below goes AFTER the tag, matching the
+ * updateDecisionsJournal inserter).
+ *
+ * @param {string} content the DECISIONS.md content
+ * @returns {string} the normalized content (idempotent)
+ */
+export function normalizeDecisionsJournal(content) {
+  if (typeof content !== 'string' || content === '') return content;
+  const lines = content.split(/\r?\n/);
+  const out = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    // A decision entry begins with the machine marker. Normalize the heading
+    // that follows it (skipping any blank lines already present).
+    if (/^<!-- decision:/.test(line)) {
+      out.push(line);
+      // ensure exactly one blank line after the marker
+      let j = i + 1;
+      while (j < lines.length && lines[j].trim() === '') j += 1; // skip existing blanks
+      out.push('');
+      // the heading line (### or ## title) — demote ### -> ##
+      if (j < lines.length && /^#{2,3}\s/.test(lines[j])) {
+        const headingText = lines[j].replace(/^#{2,3}\s+/, '');
+        out.push(`## ${headingText}`);
+        let k = j + 1;
+        // an optional retraction tag stays directly under the heading
+        if (k < lines.length && lines[k].trim().startsWith('_(retracted')) {
+          out.push(lines[k]);
+          k += 1;
+        }
+        // ensure exactly one blank line below the heading (or heading+tag)
+        while (k < lines.length && lines[k].trim() === '') k += 1; // collapse existing blanks
+        out.push('');
+        i = k - 1; // continue after the blank we just normalized
+      } else {
+        // malformed entry (marker with no heading) — leave the rest as-is
+        i = j - 1;
+      }
+      continue;
+    }
+    out.push(line);
+  }
+  // collapse any accidental >1 trailing blank, keep a single trailing newline
+  let result = out.join('\n');
+  result = trimTrailingNewlines(result) + '\n';
+  return result;
+}
+
 // --- File-IO orchestration (the impure shell over the pure core) ----------
 
 // Leading indent is [ \t]* (NOT \s*) so it can't match the newline the