@lh8ppl/claude-memory-kit 0.3.4 → 0.4.0

package/README.md

@@ -18,6 +18,7 @@
 - **Explicit capture when you want it** — say "remember this" / "from now on" / "we decided" / "forget X" (the `memory-write` skill), or run `cmk remember "<fact>"`. Both dedup, screen for secrets, abstract machine paths to `~`, and write silently. For backtick/quote-heavy rich facts, capture them shell-safe as JSON: `cmk remember --from-file fact.json` (or `--json` from stdin) — content never touches the shell.
 - **Search + MCP — Claude runs every memory op for you, in conversation** — `cmk search "<term>"` (keyword over facts + scratchpads; with the optional local embedder, **semantic + hybrid recall**: ask in your own words and get the fact even with zero keyword overlap — measured R@5 0.941 / paraphrase 1.000 on the kit's benchmark, no API calls). `cmk install` registers the kit's **MCP server**, so Claude can do the whole memory surface as tools without you ever typing `cmk`: capture (`mk_remember`, rich Why/How too), recall (`mk_search` / `mk_get` / `mk_timeline` / `mk_cite`), adjust trust (`mk_trust`), promote a fact across projects (`mk_lessons_promote`), forget (`mk_forget` — previews first, then deletes on confirm), and clear the review/conflict queues (`mk_queue_list` / `mk_queue_resolve`). The tools are allow-listed on install, so they run prompt-free.
 - **Bounded by compression** — session → daily → weekly Haiku rollups (cron or lazy-on-read) keep the snapshot small as history grows. The session-buffer rollup self-heals at session start too, so memory stays bounded even if you never cleanly close the window.
+- **Guards your memory from an accidental delete** — `cmk install` wires a `PreToolUse` hook (`cmk-guard-memory`) that **blocks** a destructive command (`rm`, `Remove-Item`, `del`, `git clean`, `git reset --hard`, `find … -delete`, `truncate`, `>`-truncate) the moment it's aimed at a memory path — *before* it runs, on both Claude Code (`Bash` / `PowerShell`) and Kiro (`execute_bash`). Fail-open (a broken guard never wedges your session) and intentionally broad (a false block is recoverable; a false allow is the data loss it prevents). A safe command, or a delete of anything else, runs untouched.
 - **Don't start empty — import the rules you already own** — `cmk import-claude-md` parses an existing `CLAUDE.md` / `.cursorrules` / `AGENTS.md` into typed, searchable facts through the same safe write path (secret screening, sanitization, dedup), with provenance back to source file + line. `--dry-run` previews first.
 - **Per-project, in-repo** — `context/` lives inside your project and travels with `git clone`. Each project keeps its own memory.
 - **9 health checks** — `cmk doctor` validates hook wiring, distill freshness, transcript firing, INDEX consistency, cron registration, native-memory coexistence, stale locks, native-binding health (npm 12 readiness), and version drift (a project scaffold behind your installed `cmk` after an update) — each failure with a repair command.
@@ -33,6 +34,7 @@ npm install -g @lh8ppl/claude-memory-kit
 cd ~/my-project
 cmk install        # scaffolds context/ + the memory-write + memory-search skills AND wires the lifecycle hooks into .claude/settings.json
 cmk install --with-semantic   # (optional) local semantic recall — one-time ~260 MB, search defaults to hybrid
+cmk install --ide kiro        # (optional) target Kiro instead — wires the IDE + kiro-cli surfaces (MCP + steering + AGENTS.md + skills + hooks)
 cmk register-crons            # (optional) scheduled background compression — otherwise self-heals lazily
 cmk import-claude-md --yes    # (optional) seed memory from an existing CLAUDE.md / .cursorrules (--dry-run previews)
 cmk doctor         # verify, then restart Claude Code
@@ -42,6 +44,10 @@ cmk doctor         # verify, then restart Claude Code
 
 > Installing the package globally adds the `cmk` CLI **and** the installer. It's the `cmk install` *subcommand* that wires the hooks — not the bare `npm install`.
 
+**Other agents (Kiro).** `cmk install --ide kiro` targets [Kiro](https://kiro.dev) (AWS's agentic IDE + `kiro-cli`) instead of Claude Code — one command wires both its GUI hooks (`.kiro/hooks/`) and its terminal CLI agent (`~/.aws/amazonq/cli-agents/`), plus MCP, steering, skills, and an `AGENTS.md` instruction file. A project can carry **both** agents (run both installs — they share one `context/` brain and never clobber each other). Restart Kiro to load its hooks.
+
+**Uninstall** is per-agent and conservative — it never deletes your `context/` memory: `cmk uninstall` removes the Claude Code surface; `cmk uninstall --ide kiro` removes the Kiro surface.
+
 ### Route B — Claude Code plugin marketplace
 
 Inside Claude Code:

package/bin/cmk-guard-memory.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// PreToolUse hook handler — the memory delete-guardrail (D-192).
+//
+// Wired by `cmk install` as a Claude Code PreToolUse hook (matcher
+// "Bash|PowerShell"). Reads the tool call on stdin and, if it's a destructive
+// command aimed at a claude-memory-kit memory path (context/ , the persona
+// tier, a memory file), BLOCKS it by exiting 2 — Claude Code shows the stderr
+// reason to the model and the command never runs.
+//
+// Exit contract (Claude Code PreToolUse):
+//   exit 0 → allow (no opinion)
+//   exit 2 → BLOCK; stderr is surfaced as the reason
+// Fail-OPEN: any load/parse error exits 0 — a broken guardrail must never wedge
+// the session; it just stops guarding.
+
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const readHookStdinPath = join(__dirname, '..', 'src', 'read-hook-stdin.mjs');
+const modulePath = join(__dirname, '..', 'src', 'guard-memory.mjs');
+
+let readHookStdin;
+let evaluatePayload;
+try {
+  ({ readHookStdin } = await import(pathToFileURL(readHookStdinPath).href));
+  ({ evaluatePayload } = await import(pathToFileURL(modulePath).href));
+} catch (err) {
+  process.stderr.write(`cmk-guard-memory: failed to load modules: ${err?.message ?? err}\n`);
+  process.exit(0); // fail-open
+}
+
+// Drain the hook payload — but not on an interactive TTY (a manual run), where
+// a blocking stdin read would hang forever (the Task-101 lesson).
+const raw = readHookStdin({ isTTY: process.stdin.isTTY });
+
+let payload;
+try {
+  payload = raw.trim() === '' ? {} : JSON.parse(raw);
+} catch {
+  process.exit(0); // fail-open on unparseable input
+}
+
+let verdict;
+try {
+  verdict = evaluatePayload(payload);
+} catch {
+  process.exit(0); // fail-open on any logic error
+}
+
+if (verdict && verdict.block) {
+  process.stderr.write(`${verdict.reason}\n`);
+  process.exit(2); // BLOCK
+}
+
+process.exit(0); // allow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lh8ppl/claude-memory-kit",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "cmk — the CLI for claude-memory-kit. Per-project, in-repo memory system for Claude Code.",
   "type": "module",
   "bin": {
@@ -12,7 +12,8 @@
     "cmk-capture-prompt": "./bin/cmk-capture-prompt.mjs",
     "cmk-observe-edit": "./bin/cmk-observe-edit.mjs",
     "cmk-capture-turn": "./bin/cmk-capture-turn.mjs",
-    "cmk-compress-session": "./bin/cmk-compress-session.mjs"
+    "cmk-compress-session": "./bin/cmk-compress-session.mjs",
+    "cmk-guard-memory": "./bin/cmk-guard-memory.mjs"
   },
   "files": [
     "bin/",

package/src/agent-profile.mjs

@@ -0,0 +1,115 @@
+// agent-profile.mjs — the per-agent profile factory (Task 50.C).
+//
+// D-180: per-agent adapters are DATA, not classes. This factory validates +
+// normalizes a profile DECLARATION so the install routing (Task 50.F) can drive
+// ANY agent through ONE code path — the config legs (MCP registration, hook
+// entry) go through the shared `mutateAgentConfig` primitive (Task 50.B); the
+// instruction leg goes through the kit's marker-block machinery. The factory
+// itself does NO I/O — it's a pure validator/normalizer that returns a frozen
+// descriptor. A bad profile fails LOUD at definition time (throws), not at
+// install time against a user's machine.
+//
+// Integration-type taxonomy (the claude-mem insight — the type dictates which
+// legs an agent wires):
+//   native-hooks-mcp   — instruction + MCP + lifecycle hooks (Claude Code, Kiro)
+//   hooks-mcp          — instruction + MCP + hooks, hooks via a dedicated file
+//                        (Cursor) — same required legs as native-hooks-mcp;
+//                        the `hooks.mechanism` field distinguishes them
+//   mcp-only           — instruction + MCP, NO hooks (Copilot/Warp/Roo/Goose)
+//   instruction-only   — instruction file only, NO MCP, NO hooks (AGENTS.md rung)
+//
+// Public surface:
+//   defineAgentProfile(declaration) → frozen normalized descriptor (throws on invalid)
+//   INTEGRATION_TYPES — frozen list of the valid integrationType values
+
+export const INTEGRATION_TYPES = Object.freeze([
+  'native-hooks-mcp',
+  'hooks-mcp',
+  'mcp-only',
+  'instruction-only',
+]);
+
+const TYPES = new Set(INTEGRATION_TYPES);
+
+// Which legs each type REQUIRES / FORBIDS. instructionFile is required by every
+// type (the universal leg). mcp + hooks vary by type.
+const TYPE_LEGS = Object.freeze({
+  'native-hooks-mcp': { mcp: 'required', hooks: 'required' },
+  'hooks-mcp': { mcp: 'required', hooks: 'required' },
+  'mcp-only': { mcp: 'required', hooks: 'forbidden' },
+  'instruction-only': { mcp: 'forbidden', hooks: 'forbidden' },
+});
+
+function fail(msg) {
+  throw new Error(`defineAgentProfile: ${msg}`);
+}
+
+/**
+ * Validate + normalize an agent profile declaration.
+ * @param {object} decl
+ * @returns {Readonly<object>} the frozen descriptor
+ */
+export function defineAgentProfile(decl) {
+  if (decl === null || typeof decl !== 'object') {
+    fail('declaration must be an object');
+  }
+  const { name, displayName, integrationType, detect, instructionFile, mcp, hooks, transcript } = decl;
+
+  // ── universal required fields ────────────────────────────────────────────
+  if (typeof name !== 'string' || name.length === 0) {
+    fail('name is required (non-empty string)');
+  }
+  if (!TYPES.has(integrationType)) {
+    fail(`integrationType must be one of: ${INTEGRATION_TYPES.join(', ')} (got ${JSON.stringify(integrationType)})`);
+  }
+  if (detect === null || typeof detect !== 'object') {
+    fail(`profile ${name}: detect descriptor is required (e.g. {homeDir:'.kiro'} | {command:'x'} | {always:true})`);
+  }
+  if (typeof instructionFile !== 'string' || instructionFile.length === 0) {
+    fail(`profile ${name}: instructionFile is required (every integration type wires the instruction leg)`);
+  }
+
+  // ── per-type leg contract (the parity invariant 50.D will also enforce) ──
+  const legs = TYPE_LEGS[integrationType];
+  enforceLeg(name, integrationType, 'mcp', mcp, legs.mcp);
+  enforceLeg(name, integrationType, 'hooks', hooks, legs.hooks);
+
+  // ── shape checks on present legs ─────────────────────────────────────────
+  if (mcp !== undefined) {
+    if (typeof mcp.path !== 'string' || typeof mcp.serversKey !== 'string') {
+      fail(`profile ${name}: mcp requires {path, serversKey} strings`);
+    }
+  }
+  if (hooks !== undefined) {
+    if (typeof hooks.mechanism !== 'string') {
+      fail(`profile ${name}: hooks requires a {mechanism} string`);
+    }
+    if (hooks.eventMap === null || typeof hooks.eventMap !== 'object') {
+      fail(`profile ${name}: hooks requires an {eventMap} object`);
+    }
+  }
+
+  // ── normalize + freeze ───────────────────────────────────────────────────
+  const descriptor = {
+    name,
+    displayName: displayName || name,
+    integrationType,
+    detect: Object.freeze({ ...detect }),
+    instructionFile,
+    ...(mcp !== undefined ? { mcp: Object.freeze({ ...mcp }) } : {}),
+    ...(hooks !== undefined
+      ? { hooks: Object.freeze({ ...hooks, eventMap: Object.freeze({ ...hooks.eventMap }) }) }
+      : {}),
+    ...(transcript !== undefined ? { transcript: Object.freeze({ ...transcript }) } : {}),
+  };
+  return Object.freeze(descriptor);
+}
+
+function enforceLeg(name, type, leg, value, requirement) {
+  if (requirement === 'required' && value === undefined) {
+    fail(`profile ${name}: integrationType '${type}' requires the ${leg} leg`);
+  }
+  if (requirement === 'forbidden' && value !== undefined) {
+    fail(`profile ${name}: integrationType '${type}' must NOT declare ${leg} (it over-wires its type)`);
+  }
+}

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/auto-persona.mjs

@@ -421,7 +421,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/compress-retry.mjs

@@ -37,6 +37,31 @@
 // a time, gated by the cooldown), so there is no herd to avoid — a plain exponential
 // backoff is sufficient and keeps the timing deterministic for tests.
 
+// The timeout for compress callers that have NO outer hook ceiling — the cron /
+// detached-lazy children (daily-distill, weekly-curate, the lazy compressSession).
+// The D-92/F-2 composition rule: a ceiling-free caller must NOT inherit the
+// hook-sized 50s bound (which is sized under the 60s SessionEnd ceiling, §8.5).
+// 120s is chosen against MEASURED `claude --print` latency: it runs ~18-27s when
+// fast but was observed at 78s (Task 163 live, on a 4.7KB input) and 89s (the v0.3.4
+// cut-gate, 10KB) in slow-Haiku windows — environmental, not size-driven (D-174).
+// 120s clears those with headroom; the 50s budget killed them needlessly, leaving
+// `recent.md` stale (D-179). One constant so the family can't drift back to 50s.
+// (auto-extract uses its own 90s under the Stop hook — a separate detached path.)
+export const CEILING_FREE_TIMEOUT_MS = 120_000;
+
+// The backoff BETWEEN retries on the ceiling-free paths. The default baseBackoffMs
+// (600ms) is far too short for the kit's failure mode: `claude --print` slowness is
+// a transient WINDOW (slow for a stretch, then fine — D-174), and the whole point of
+// backoff is to let that window PASS before retrying. A 600ms wait retries while
+// still INSIDE the same slow window, so attempt 2 hits the same slowness and also
+// times out. The field waits SECONDS for exactly this reason (graphiti 5-120s,
+// Letta cap 10s, mempalace 2-8s — all checked across 19 systems; NONE use sub-second
+// backoff, and NONE escalate the timeout itself). 5s is the field's low end — one
+// 5s wait between the 2 ceiling-free attempts gives the slow window room to clear.
+// Safe on every path: the HOOK path is maxAttempts:1 (no retry → backoff never
+// fires); the ceiling-free paths run detached/cron, so a multi-second wait is free.
+export const CEILING_FREE_BACKOFF_MS = 5_000;
+
 /**
  * Classify a compress() rejection as transient (worth a retry) or deterministic
  * (a re-call re-fails identically — don't waste the attempt or the budget).

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;
 }
 
@@ -232,6 +244,16 @@ export async function compressSession({
   // caller (runLazyCompress) passes maxAttempts:2 to opt into one retry; the hook
   // keeps its restore-on-failure (D-79) and delegates the retry to that lazy path.
   maxAttempts = 1,
+  // DEFAULT 50s = the SessionEnd-hook budget (sized under the 60s ceiling, §8.5).
+  // The ceiling-free LAZY caller (runLazyCompress, a detached SessionStart child
+  // with NO outer ceiling) passes 120s so a slow-but-not-broken `claude --print`
+  // window doesn't time out needlessly — the D-92/F-2 composition rule: a
+  // ceiling-free caller must not inherit a ceiling-sized timeout.
+  timeoutMs = 50_000,
+  // Backoff between retries (only the lazy maxAttempts:2 path retries). DEFAULT
+  // undefined → compressWithRetry's 600ms; the ceiling-free LAZY caller passes the
+  // 5s ceiling-free backoff so a retry lands AFTER the slow-Haiku window (D-179).
+  baseBackoffMs,
 } = {}) {
   const ts = now ?? nowIso();
   const date = dateFromIso(ts);
@@ -343,9 +365,11 @@ export async function compressSession({
         instructions,
         preserveCitationIds: true,
         maxOutputBytes,
-        timeoutMs: 50_000,
+        timeoutMs,
       },
-      { maxAttempts, onRetry: () => { retries += 1; } },
+      // baseBackoffMs only forwarded when the caller set it (the lazy ceiling-free
+      // path passes the 5s backoff); undefined → compressWithRetry's 600ms default.
+      { maxAttempts, ...(baseBackoffMs != null ? { baseBackoffMs } : {}), onRetry: () => { retries += 1; } },
     );
   } catch (err) {
     // Distinguish HAIKU_TIMEOUT (slow Anthropic) from COMPRESS_FAILED

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/daily-distill.mjs

@@ -28,7 +28,7 @@ import { join } from 'node:path';
 import { nowIso } from './audit-log.mjs';
 import { ERROR_CATEGORIES } from './result-shapes.mjs';
 import { HaikuTimeoutError } from './compressor.mjs';
-import { compressWithRetry } from './compress-retry.mjs';
+import { compressWithRetry, CEILING_FREE_TIMEOUT_MS, CEILING_FREE_BACKOFF_MS } from './compress-retry.mjs';
 import {
   DEFAULT_COOLDOWN_MS,
   isCooldownActive,
@@ -209,9 +209,13 @@ export async function dailyDistill({
         instructions,
         preserveCitationIds: true,
         maxOutputBytes,
-        timeoutMs: 50_000,
+        // Ceiling-free (cron / detached lazy child, NO 60s hook ceiling) → the
+        // generous ceiling-free timeout, NOT the hook-sized 50s (D-92/F-2 + D-179).
+        timeoutMs: CEILING_FREE_TIMEOUT_MS,
       },
-      { maxAttempts: 2, onRetry: () => { retries += 1; } },
+      // 5s backoff between the 2 attempts (NOT the 600ms default) so a retry lands
+      // AFTER the transient slow-Haiku window, not inside it (D-179).
+      { maxAttempts: 2, baseBackoffMs: CEILING_FREE_BACKOFF_MS, onRetry: () => { retries += 1; } },
     );
     touchCooldownMarker({ projectRoot, now: ts });
   } catch (err) {

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