@lh8ppl/claude-memory-kit 0.1.2 → 0.2.1

package/src/scratchpad.mjs

@@ -17,7 +17,14 @@
 // this module will call instead. The handoff is clean: format stays identical;
 // only the location of the formatter moves.
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  appendFileSync,
+  mkdirSync,
+} from 'node:fs';
+import { join } from 'node:path';
 import { generateId } from '@lh8ppl/cmk-canonicalize';
 import {
   VALID_TIERS,
@@ -28,7 +35,8 @@ import {
 } from './tier-paths.mjs';
 import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
-import { writeBullet, parseBulletProvenance } from './provenance.mjs';
+import { writeBullet, parseBulletProvenance, isProvenanceCommentLine } from './provenance.mjs';
+import { graduateForCapRelief } from './graduation.mjs';
 
 const VALID_TRUST = new Set(['high', 'medium', 'low']);
 const VALID_WRITE_SOURCES = new Set([
@@ -188,9 +196,33 @@ function insertIntoSection(text, sectionTitle, bullet) {
   return lines.join('\n');
 }
 
+/**
+ * Ensure a `## <sectionTitle>` heading exists in a scratchpad file, creating
+ * it (appended at EOF, with clean spacing) if absent. Used by the persona
+ * promoter (Task 64 / F2) so a cross-project candidate routed to a sane-but-
+ * new section lands instead of schema-failing to the review queue. The CALLER
+ * owns the name-safety guard — this only writes the heading.
+ *
+ * @returns {{created: boolean, error?: string}}
+ */
+export function ensureSectionExists(scratchpadPath, sectionTitle) {
+  if (!existsSync(scratchpadPath)) return { created: false, error: 'no-file' };
+  const text = readFileSync(scratchpadPath, 'utf8');
+  if (findSectionRange(text.split('\n'), sectionTitle)) return { created: false };
+  const body = text.trimEnd(); // drop trailing whitespace/blank lines (no `\s+$` regex — trips ReDoS heuristics)
+  // 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');
+  return { created: true };
+}
+
+const EVICTED_ID_RE = /^- \(([PUL]-[A-Za-z0-9]+)\)/;
+
 function consolidate(text, { nowDate }) {
   const lines = text.split('\n');
   const removeIdx = new Set();
+  const evicted = [];
   const staleCutoff = new Date(nowDate.getTime() - STALE_AFTER_DAYS * 24 * 60 * 60 * 1000);
   let bulletsRemoved = 0;
 
@@ -199,7 +231,7 @@ function consolidate(text, { nowDate }) {
     const bulletLine = lines[i];
     const commentLine = lines[i + 1];
     if (!bulletLine.startsWith('- (')) continue;
-    if (!commentLine || !/^\s*<!--.*-->\s*$/.test(commentLine)) continue;
+    if (!isProvenanceCommentLine(commentLine)) continue;
 
     const prov = parseBulletProvenance(commentLine);
     if (!prov || !prov.at || !prov.trust) continue;
@@ -211,14 +243,47 @@ function consolidate(text, { nowDate }) {
 
     removeIdx.add(i);
     removeIdx.add(i + 1);
+    // Task 91.2: capture the dropped bullet so the caller can ARCHIVE it
+    // (recoverable, per the §6.5 tombstone principle) instead of hard-deleting.
+    const idMatch = bulletLine.match(EVICTED_ID_RE);
+    evicted.push({ id: idMatch ? idMatch[1] : 'unknown', block: `${bulletLine}\n${commentLine}` });
     bulletsRemoved++;
   }
 
   if (removeIdx.size === 0) {
-    return { text, bulletsRemoved: 0 };
+    return { text, bulletsRemoved: 0, evicted: [] };
   }
   const out = lines.filter((_, i) => !removeIdx.has(i)).join('\n');
-  return { text: out, bulletsRemoved };
+  return { text: out, bulletsRemoved, evicted };
+}
+
+// Task 91.2: archive bullets that consolidate() dropped, so eviction is
+// recoverable rather than silent (mirrors `cmk forget`'s tombstone, §6.5).
+// Append-only log under the tier's archive dir; one audit entry per bullet.
+const EVICTED_ARCHIVE_HEADER =
+  '# Evicted scratchpad bullets\n\n<!-- Bullets dropped by cap-consolidation (low/medium trust, >14 days old). Kept here so eviction is recoverable, not silent. To restore one, re-capture it via `cmk remember`. -->\n\n';
+
+function archiveEvictedBullets({ tierRoot, tier, scratchpad, evicted, now }) {
+  const archiveDir = join(tierRoot, 'memory', 'archive');
+  mkdirSync(archiveDir, { recursive: true });
+  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
+    .map((e) => e.block)
+    .join('\n')}\n\n`;
+  appendFileSync(archivePath, header + block, 'utf8');
+  for (const e of evicted) {
+    appendAuditEntry(tierRoot, {
+      ts,
+      action: 'evicted',
+      tier,
+      id: e.id,
+      reasonCode: REASON_CODES.SCRATCHPAD_EVICTED,
+      paths: { archive: archivePath },
+      extra: { scratchpad },
+    });
+  }
 }
 
 export function appendScratchpadBullet(opts = {}) {
@@ -275,6 +340,7 @@ export function appendScratchpadBullet(opts = {}) {
   // 2. Cap check: would the write push to >95%? If yes, consolidate.
   let consolidationRan = false;
   let bulletsConsolidated = 0;
+  let evictedBullets = [];
   let finalContent = candidate;
   const candidateBytes = Buffer.byteLength(candidate, 'utf8');
 
@@ -284,28 +350,72 @@ export function appendScratchpadBullet(opts = {}) {
     const consolidated = consolidate(candidate, { nowDate });
     bulletsConsolidated = consolidated.bulletsRemoved;
     finalContent = consolidated.text;
+    evictedBullets = consolidated.evicted ?? [];
   }
 
-  // 3. Post-consolidation cap check
-  const finalBytes = Buffer.byteLength(finalContent, 'utf8');
-  if (finalBytes > cap) {
-    // File untouched. The original on-disk content is preserved verbatim.
-    return errorResult({
-      category: ERROR_CATEGORIES.CAP_EXCEEDED,
-      errors: [
-        `scratchpad cap exceeded: ${finalBytes} bytes would exceed cap of ${cap} bytes for ${scratchpad} (consolidator dropped ${bulletsConsolidated} bullet(s), still over). No silent truncation; resolve by raising the cap in settings.json or manually distilling.`,
-      ],
-      path,
-      cap,
-      bytes: finalBytes,
-      consolidationRan,
-      bulletsConsolidated,
+  // 2b. Graduation (Task 91, generalized to all tiers by Task 94 / §19.2). If
+  // still over the LOAD-cap after stale-drop — which is what happens when the
+  // bullets are high-trust (consolidate() never drops those) — graduate the
+  // oldest high-trust bullets OUT of the hot index into the tier's permanent
+  // fact store, keeping the injected slice small (the write already succeeded
+  // via the load-cap; graduation is about injection budget, not write success).
+  // ALL FACT-BEARING TIERS (D-61): project (MEMORY.md + SOUL.md) AND the user-
+  // tier persona (USER/HABITS/LESSONS) — graduating into the tier's existing
+  // fact store (project context/memory/, user <userDir>/fragments/; writeFact
+  // already routes tier-U facts there). Local tier (machine-paths/overrides) is
+  // excluded: it's machine-specific config, not durable facts.
+  let bulletsGraduated = 0;
+  let graduatedIds = [];
+  let finalBytes = Buffer.byteLength(finalContent, 'utf8');
+  if (finalBytes > cap && (tier === 'P' || tier === 'U')) {
+    const grad = graduateForCapRelief({
+      text: finalContent,
+      capBytes: cap,
+      tier,
+      projectRoot,
+      userDir,
+      now,
     });
+    finalContent = grad.text;
+    graduatedIds = grad.graduated;
+    bulletsGraduated = graduatedIds.length;
+    finalBytes = Buffer.byteLength(finalContent, 'utf8');
   }
 
+  // 3. Load-cap, NOT write-cap (Task 94 / D-61 / design §19). The write ALWAYS
+  // succeeds — the cap governs only how much is injected, never whether content
+  // can be saved (the never-lose-memory invariant). When consolidate + graduation
+  // can't bring the file under cap (e.g. an absurdly small cap, or a single large
+  // bullet), the file is allowed to GROW past the inject budget; inject-context
+  // load-caps the snapshot (§7.1.1) and the overflow stays searchable on disk.
+  // The old `cap_exceeded` reject path was removed here — see §19.5 for the
+  // superseded write-cap design and why it changed.
+
   // 4. Write + audit
   writeFileSync(path, finalContent, 'utf8');
   const ts = now ?? nowIso();
+
+  // 4a. Task 91.2 — archive evicted bullets now that the drop is durable on
+  // disk (only on the success path, so we never archive a bullet that's still
+  // live in the unchanged on-disk scratchpad).
+  if (evictedBullets.length > 0) {
+    archiveEvictedBullets({ tierRoot, tier, scratchpad, evicted: evictedBullets, now: ts });
+  }
+  // 4b. Task 91.4 (Door 4) — one audit entry per graduated bullet, so the
+  // bullet→fact-file move is traceable in the audit log (writeFact also logs
+  // the fact create; this records the graduation that triggered it).
+  for (const gid of graduatedIds) {
+    appendAuditEntry(tierRoot, {
+      ts,
+      action: 'graduated',
+      tier,
+      id: gid,
+      reasonCode: REASON_CODES.SCRATCHPAD_GRADUATED,
+      paths: { after: path },
+      extra: { scratchpad },
+    });
+  }
+
   appendAuditEntry(tierRoot, {
     ts,
     action: 'appended',
@@ -320,6 +430,7 @@ export function appendScratchpadBullet(opts = {}) {
       bytes: finalBytes,
       consolidationRan,
       bulletsConsolidated,
+      bulletsGraduated,
     },
   });
 
@@ -331,5 +442,122 @@ export function appendScratchpadBullet(opts = {}) {
     bytes: finalBytes,
     consolidationRan,
     bulletsConsolidated,
+    bulletsGraduated,
+  };
+}
+
+/**
+ * Proactive cap-relief for a SINGLE scratchpad, run OUTSIDE the append path
+ * (Task 94.3). The reactive relief inside appendScratchpadBullet only fires when
+ * a write triggers cap pressure; this lets a SessionEnd sweep keep the injected
+ * slice under its load-cap even in a read-only session (no new bullets) and catch
+ * low/medium bullets that AGED past the 14-day stale window between sessions.
+ *
+ * Runs the SAME relief sequence as the append path — consolidate (stale-drop +
+ * archive) then graduate (high-trust overflow → the tier's fact store) — but only
+ * when the scratchpad is already over its load-cap, and it writes back ONLY if
+ * the content actually changed (no churn / no audit noise on a comfortable
+ * scratchpad, satisfying the over-mutation guard). The WHOLE relief (consolidate
+ * AND graduate) is gated to fact-bearing tiers P + U; the L tier (machine config)
+ * is left untouched even when over cap — its bullets are not durable facts.
+ *
+ * Cost note (hook-ceiling composition): each graduated bullet flows through
+ * writeFact, which reindexes — so a sweep that graduates N bullets does N reindex
+ * passes. That mirrors the reactive append path's existing per-graduating-bullet
+ * cost; at SessionEnd it runs AFTER the ~50s concurrent Haiku block but is local
+ * file I/O (no spawn/network), and the SessionEnd hook is best-effort (exits 0 on
+ * overrun), so it does not threaten the 60s ceiling in practice.
+ *
+ * @returns {{action:'relieved'|'noop'|'skipped', reason?:string, tier:string,
+ *   scratchpad:string, bulletsConsolidated:number, bulletsGraduated:number,
+ *   graduatedIds:string[], bytes:number}}
+ */
+export function sweepScratchpadForCapRelief({
+  tier,
+  scratchpad,
+  projectRoot,
+  userDir,
+  now,
+  settings,
+}) {
+  const base = {
+    tier,
+    scratchpad,
+    bulletsConsolidated: 0,
+    bulletsGraduated: 0,
+    graduatedIds: [],
+    bytes: 0,
+  };
+  const path = resolveScratchpadPath({ tier, scratchpad, projectRoot, userDir });
+  if (!existsSync(path)) {
+    return { ...base, action: 'skipped', reason: 'no-file' };
+  }
+
+  const original = readFileSync(path, 'utf8');
+  const cap = resolveCap({ tier, scratchpad, projectRoot, userDir, settings });
+  const originalBytes = Buffer.byteLength(original, 'utf8');
+  if (originalBytes <= cap) {
+    // Load-cap respected already — leave it alone (no churn).
+    return { ...base, action: 'noop', bytes: originalBytes };
+  }
+  // Relief (both consolidate AND graduate) applies only to fact-bearing tiers.
+  // Gate here so the consolidate stale-drop can never touch L-tier machine config
+  // even if a future caller passes it (graduateAllScratchpads never does today).
+  if (tier !== 'P' && tier !== 'U') {
+    return { ...base, action: 'noop', reason: 'tier-excluded', bytes: originalBytes };
+  }
+
+  // Over cap — run the same relief sequence as appendScratchpadBullet.
+  const ts = now ?? nowIso();
+  const tierRoot = resolveTierRoot({ tier, projectRoot, userDir });
+
+  const consolidated = consolidate(original, { nowDate: new Date(ts) });
+  let working = consolidated.text;
+  const evicted = consolidated.evicted ?? [];
+
+  let graduatedIds = [];
+  if (Buffer.byteLength(working, 'utf8') > cap) {
+    // tier is already guaranteed P||U by the gate above.
+    const grad = graduateForCapRelief({
+      text: working,
+      capBytes: cap,
+      tier,
+      projectRoot,
+      userDir,
+      now: ts,
+    });
+    working = grad.text;
+    graduatedIds = grad.graduated;
+  }
+
+  if (working === original) {
+    // Nothing relievable (no stale bullets to drop; graduation infeasible or no
+    // eligible high-trust bullets). Load-cap means over-cap is allowed — leave
+    // the file untouched rather than rewriting it identically.
+    return { ...base, action: 'noop', reason: 'irreducible', bytes: originalBytes };
+  }
+
+  writeFileSync(path, working, 'utf8');
+  if (evicted.length > 0) {
+    archiveEvictedBullets({ tierRoot, tier, scratchpad, evicted, now: ts });
+  }
+  for (const gid of graduatedIds) {
+    appendAuditEntry(tierRoot, {
+      ts,
+      action: 'graduated',
+      tier,
+      id: gid,
+      reasonCode: REASON_CODES.SCRATCHPAD_GRADUATED,
+      paths: { after: path },
+      extra: { scratchpad, trigger: 'session-end' },
+    });
+  }
+  return {
+    ...base,
+    action: 'relieved',
+    bulletsConsolidated: evicted.length,
+    bulletsGraduated: graduatedIds.length,
+    graduatedIds,
+    bytes: Buffer.byteLength(working, 'utf8'),
   };
 }

package/src/session-end-tasks.mjs

@@ -0,0 +1,127 @@
+// SessionEnd orchestrator (Task 86b + D-42). The shared brain behind both
+// cmk-compress-session bins (npm: packages/cli/bin/; plugin: plugin/bin/) —
+// extracted so the orchestration lives in ONE testable place instead of being
+// duplicated across the twin bins (the twin-bin drift hazard CLAUDE.md warns
+// about).
+//
+// What it does: at session end we run TWO independent Haiku passes —
+//   1. compressSession — reads sessions/now.md (the session buffer) → writes
+//      sessions/today-{date}.md, truncates now.md, appends compress.log.
+//   2. autoPersona — reads the context/memory/ fact corpus (written per-turn by
+//      auto-extract, NOT by compressSession) → promotes cross-project doctrine
+//      into the user-tier persona scratchpads.
+//
+// They have DISJOINT inputs and DISJOINT outputs (compress touches the project
+// sessions/ tree; persona touches the user-tier scratchpads + audit.log; neither
+// reads the other's writes; neither takes a lock the other needs). So we run them
+// CONCURRENTLY via Promise.allSettled.
+//
+// Why concurrent, not sequential (the D-42 composition fix): each pass carries a
+// 50s inner Haiku timeout, and the SessionEnd hook ceiling is 60s (design §8.5 /
+// plugin/hooks/hooks.json). Run sequentially, the worst case is 50s + 50s = 100s
+// — well over the ceiling, so the OS would kill the hook mid-persona-write,
+// dropping {"continue": true} AND risking a half-written user-tier INDEX (HC-5
+// corruption, shared across every project). Run concurrently, the wall-clock is
+// max(50s, 50s) ≈ 50s — comfortably inside 60s. compressSession is correct alone
+// (50<60); autoPersona is correct alone (50<60); only their SEQUENTIAL composition
+// was broken. Concurrency is the composition fix.
+//
+// allSettled (not all): both passes are best-effort. A failure in one must never
+// discard the other's result, and must never reject up into the hook (a thrown
+// SessionEnd hook blocks the user from closing their terminal). Each pass gets its
+// OWN backend instance (makeBackend factory) so there is zero shared mutable state
+// across the two concurrent calls.
+
+import { compressSession } from './compress-session.mjs';
+import { autoPersona } from './auto-persona.mjs';
+import { graduateAllScratchpads } from './graduate-session.mjs';
+
+/**
+ * Run the two independent SessionEnd Haiku passes concurrently.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectRoot - resolved project root (CMK_PROJECT_DIR or cwd).
+ * @param {string} opts.userDir - user-tier root (~/.claude-memory-kit or override).
+ * @param {() => object} opts.makeBackend - factory returning a fresh CompressorBackend
+ *   per call (each concurrent pass gets its own instance — no shared state).
+ * @param {string} [opts.now] - ISO timestamp override (tests).
+ * @returns {Promise<{compressOutcome: PromiseSettledResult, personaOutcome: PromiseSettledResult, graduationOutcome: PromiseSettledResult}>}
+ */
+export async function runSessionEndTasks({ projectRoot, userDir, makeBackend, now }) {
+  const [compressOutcome, personaOutcome] = await Promise.allSettled([
+    compressSession({ projectRoot, backend: makeBackend(), now }),
+    // cooldownMs:0 — compressSession runs concurrently and would otherwise trip the
+    // shared 120s Haiku cooldown gate; at SessionEnd we explicitly want persona to run.
+    // source:'transcript' (Task 86c / D-44) — classify the RAW recent conversation,
+    // where standing-rule statements survive verbatim, NOT the distilled fact corpus
+    // (which strips the cross-project signal). This is what makes the cold-open work.
+    autoPersona({ projectRoot, userDir, backend: makeBackend(), cooldownMs: 0, now, source: 'transcript' }),
+  ]);
+
+  // Task 94.3: proactive graduation sweep. SEQUENTIAL, AFTER the concurrent block —
+  // autoPersona WRITES the user-tier persona scratchpads and graduation READS+
+  // rewrites them, so they share inputs and must NOT overlap (the §6.8/§7.1
+  // disjoint-input rule). Running it here means the sweep sees the freshly-promoted
+  // persona, then trims any overflow so the next session's injected slice stays
+  // under its load-cap. Pure local file I/O (no Haiku/network) → adds <<1s, no
+  // hook-ceiling risk. Wrapped so a synchronous throw can't reject up into the hook.
+  let graduationOutcome;
+  try {
+    graduationOutcome = {
+      status: 'fulfilled',
+      value: graduateAllScratchpads({ projectRoot, userDir, now }),
+    };
+  } catch (err) {
+    graduationOutcome = { status: 'rejected', reason: err };
+  }
+
+  return { compressOutcome, personaOutcome, graduationOutcome };
+}
+
+/**
+ * Render the two outcomes into stderr diagnostic lines (shared by both bins so
+ * the log shape can't drift between them). Pure — returns an array of lines, each
+ * already newline-terminated.
+ *
+ * @param {{compressOutcome: PromiseSettledResult, personaOutcome: PromiseSettledResult}} outcomes
+ * @returns {string[]}
+ */
+export function summarizeSessionEnd({ compressOutcome, personaOutcome, graduationOutcome }) {
+  const lines = [];
+
+  if (compressOutcome.status === 'fulfilled') {
+    const r = compressOutcome.value ?? {};
+    const reason = r.reason ? ` (${r.reason})` : '';
+    const bytes = r.bytesIn ? ` (in: ${r.bytesIn}b, out: ${r.bytesOut}b)` : '';
+    lines.push(`cmk-compress-session: ${r.action}${reason}${bytes} ms: ${r.duration_ms ?? 0}\n`);
+  } else {
+    const e = compressOutcome.reason;
+    lines.push(`cmk-compress-session: unexpected error: ${e?.message ?? e}\n`);
+  }
+
+  if (personaOutcome.status === 'fulfilled') {
+    const p = personaOutcome.value ?? {};
+    lines.push(
+      `cmk-compress-session: persona ${p.action} (promoted: ${p.promoted?.length ?? 0}, queued: ${p.queued?.length ?? 0})\n`,
+    );
+  } else {
+    const e = personaOutcome.reason;
+    lines.push(`cmk-compress-session: persona refresh failed: ${e?.message ?? e}\n`);
+  }
+
+  // graduationOutcome is optional so pre-94.3 callers (and the orchestrator tests
+  // that pass only the two Haiku outcomes) still render exactly two lines.
+  if (graduationOutcome) {
+    if (graduationOutcome.status === 'fulfilled') {
+      const g = graduationOutcome.value ?? {};
+      lines.push(
+        `cmk-compress-session: graduation (graduated: ${g.totalGraduated ?? 0}, consolidated: ${g.totalConsolidated ?? 0})\n`,
+      );
+    } else {
+      const e = graduationOutcome.reason;
+      lines.push(`cmk-compress-session: graduation failed: ${e?.message ?? e}\n`);
+    }
+  }
+
+  return lines;
+}

package/src/settings-hooks.mjs

@@ -34,9 +34,12 @@
 //
 //   **Original block (pre-2026-05-29, repair.mjs)**: the PLUGIN form,
 //   `bash "${CLAUDE_PLUGIN_ROOT}/bin/<name>"`, 6 events incl. Setup →
-//   cmk-version-check. That form is correct ONLY when the plugin is
-//   loaded (CLAUDE_PLUGIN_ROOT is set + bash is present). It still lives
-//   in plugin/hooks/hooks.json for the PLUGIN route (Route B), unchanged.
+//   cmk-version-check. That form required bash to be present. It lives in
+//   plugin/hooks/hooks.json for the PLUGIN route (Route B) — and as of
+//   Task 62 (2026-05-31) that route was converted to the node form
+//   `node "${CLAUDE_PLUGIN_ROOT}/bin/<name>.mjs"`, so BOTH routes are now
+//   bash-free (node-only, cross-OS). version-check was ported to a node
+//   .mjs stub at that point (see below).
 //
 //   **Task 49 (2026-05-29)**: the npm route (Route A) needs hooks that
 //   work with NO plugin loaded. This block is that form. It drops the
@@ -174,6 +177,33 @@ export function writeKitHooks(settingsPath) {
     }
   }
 
+  // Task 79 + 90: allow-list the kit's own surfaces so the agent's EXPLICIT
+  // captures stay seamless (the AUTO hook path already is). Two prompts to
+  // suppress, because Task 69 made the SKILL the capture delivery path:
+  //   - `Bash(cmk:*)` (Task 79) — stops "Allow this bash command?" when the
+  //     agent runs `cmk remember` / `cmk lessons promote` (prefix-wildcard;
+  //     matches any `cmk <subcommand> …`).
+  //   - `Skill(memory-write)` (Task 90) — stops "Use skill /memory-write?" when
+  //     the model INVOKES the capture skill. The bash rule alone doesn't cover
+  //     this: the skill-invocation gate is a separate Claude Code permission
+  //     surface (`Skill(<name>)` rule, per code.claude.com/docs/en/permissions).
+  //     Surfaced by the v0.2.0 cut-gate live run — the friction Task 79 killed
+  //     returned one layer up once capture moved into the skill.
+  // Idempotent + over-mutation safe: preserve the user's existing allow entries;
+  // only append ours if absent.
+  const KIT_ALLOW = ['Bash(cmk:*)', 'Skill(memory-write)'];
+  if (!settings.permissions || typeof settings.permissions !== 'object') {
+    settings.permissions = {};
+  }
+  if (!Array.isArray(settings.permissions.allow)) {
+    settings.permissions.allow = [];
+  }
+  for (const rule of KIT_ALLOW) {
+    if (!settings.permissions.allow.includes(rule)) {
+      settings.permissions.allow.push(rule);
+    }
+  }
+
   const after = JSON.stringify(settings);
   const changed = before !== after;