@lh8ppl/claude-memory-kit 0.1.2 → 0.2.0

package/src/capture-turn.mjs

@@ -139,6 +139,50 @@ function readLastUserTurnFromTranscript(transcriptPath) {
   return body.join('\n');
 }
 
+// Task 87: append the turn's CONVERSATION to the compression buffer
+// (context/sessions/now.md). Before this, now.md was fed ONLY by observe-edit's
+// file-write lines ("[ts] Write file=X lines=N"), so the SessionEnd compressor
+// summarized a list of filenames and hallucinated content the dialogue never
+// contained (lior-test-6: "Flask app: app.py" — inferred a framework from a
+// filename). Buffering the actual user+assistant turns here means the summary
+// reflects what was DISCUSSED. Same `## <ts> — speaker` shape as the transcript
+// so the compressor reads it as dialogue; now.md is truncated after each compress
+// (compress-session), so this is a transient session buffer, not a second store.
+// Best-effort: a now.md write failure must not abort the capture (the transcript
+// is already the durable record).
+// Per-turn cap on the ASSISTANT contribution to now.md (skill-review I1). compress
+// returns on cooldown BEFORE truncating now.md (compress-session §8.2), and
+// auto-extract refreshes the shared cooldown every turn — so during an active
+// session now.md is NOT truncated and accumulates. A verbose assistant response
+// (code dumps, long explanations) is far larger than the old file-write line, so
+// we bound each assistant turn's footprint. The USER turn is left FULL — it's
+// short and carries the standing rules/decisions we must not truncate. The
+// residual many-short-turns growth is bounded by the eventual truncate +
+// compress's 50s-timeout/degradation backstop; offset-based compression is the
+// v0.2.x escalation if mega-sessions ever bite.
+const NOW_MD_ASSISTANT_CAP = 4000;
+
+function appendConversationToNowMd({ projectRoot, ts, userTurn, assistantTurn }) {
+  const sessionsDir = join(projectRoot, 'context', 'sessions');
+  const nowMdPath = join(sessionsDir, 'now.md');
+  const blocks = [];
+  if (userTurn && userTurn.trim() !== '') {
+    blocks.push(`## ${ts} — user\n\n${userTurn}\n`);
+  }
+  let asst = assistantTurn ?? '';
+  if (asst.length > NOW_MD_ASSISTANT_CAP) {
+    asst = asst.slice(0, NOW_MD_ASSISTANT_CAP) + '\n…[assistant turn truncated for the session buffer]';
+  }
+  blocks.push(`## ${ts} — assistant\n\n${asst}\n`);
+  try {
+    if (!existsSync(sessionsDir)) mkdirSync(sessionsDir, { recursive: true });
+    appendFileSync(nowMdPath, blocks.join('\n') + '\n', 'utf8');
+  } catch {
+    // Best-effort — the transcript is the durable record; a missing now.md
+    // entry only means this turn isn't in the next session summary.
+  }
+}
+
 // Assemble the both-turns temp-file body. Both turns are sanitized
 // upstream — the user body comes from the transcript (which
 // capture-prompt sanitized when writing it) and the assistant body
@@ -176,6 +220,11 @@ function spawnAutoExtract(autoExtractPath, turnFile, projectRoot) {
         detached: true,
         stdio: 'ignore',
         cwd: projectRoot,
+        // Task 81: suppress the Windows console window the detached child
+        // would otherwise flash. (This site spawns `node` directly already,
+        // so windowsHide is effective here — unlike the legacy shell:true
+        // lazy-compress spawn, which also needed the node-direct fix.)
+        windowsHide: true,
         env: { ...process.env, CMK_PROJECT_DIR: projectRoot },
       },
     );
@@ -227,6 +276,11 @@ export function captureTurn({
   //    wrote it before this Stop fired); the assistant portion is the
   //    `sanitized` text we just appended above.
   const userTurn = readLastUserTurnFromTranscript(transcriptPath);
+
+  // Task 87: buffer the conversation into now.md so the SessionEnd compressor
+  // summarizes the DIALOGUE, not observe-edit's filename log. Best-effort.
+  appendConversationToNowMd({ projectRoot, ts, userTurn, assistantTurn: sanitized });
+
   const turnFile = join(transcriptsDir, `.extract-${Date.now()}.tmp`);
   try {
     writeFileSync(

package/src/compress-session.mjs

@@ -89,18 +89,16 @@ function buildCompressionInstructions(maxOutputBytes) {
     '## Open Questions',
     '- <one bullet per unresolved question raised during the session, ≤80 chars>',
     '',
-    '## Files Touched',
-    '- path: <relative path> — <verb summary> (cites: [#P-XXXXXXXX])',
-    '',
     '## Active Threads',
     '- <one bullet per work-in-progress thread the next session should resume, ≤80 chars>',
     '',
     'HARD RULES:',
-    '  1. Preserve every citation ID matching /#[ULP]-[A-Z0-9]{6,8}/ verbatim. Never invent new IDs.',
-    `  2. Total output ≤ ${maxOutputBytes} bytes.`,
-    '  3. If a section has no entries, omit the heading entirely (do not emit an empty heading).',
-    '  4. No prose around the headings — only the bulleted list per section.',
-    '  5. Your output goes directly into the next session\'s memory. Do not address the user, do not refer to yourself, do not narrate.',
+    '  1. Every bullet must be grounded in the session buffer below. Do not infer or guess any fact not explicitly stated in the buffer. Do not carry forward content from earlier summaries. When the buffer corrects, replaces, or reverses something stated earlier, keep ONLY the latest version of that fact — never list the superseded one alongside it (this resolves contradictions, NOT coexisting facts on different points). If unsure, omit it.',
+    '  2. Preserve every citation ID matching /#[ULP]-[A-Z0-9]{6,8}/ verbatim. Never invent new IDs.',
+    `  3. Total output ≤ ${maxOutputBytes} bytes.`,
+    '  4. If a section has no entries, omit the heading entirely (do not emit an empty heading).',
+    '  5. No prose around the headings — only the bulleted list per section.',
+    '  6. Your output goes directly into the next session\'s memory. Do not address the user, do not refer to yourself, do not narrate.',
     '',
     `The session buffer to compress appears below between the ${SESSION_BUFFER_DELIMITER} and ${SESSION_BUFFER_END_DELIMITER} markers.`,
   ].join('\n');

package/src/compressor.mjs

@@ -14,7 +14,7 @@
 // v0.2 candidates per ADR-0008: BedrockHaiku, LocalLlama; selected via
 // settings.json (`compressor.backend`).
 //
-// Sandbox flags (cd /tmp, env -u CLAUDECODE, --allowed-tools "",
+// Sandbox flags (cd /tmp, env -u CLAUDECODE, --tools "" + --allowed-tools "",
 // --max-turns 1, --mcp-config '{"mcpServers":{}}' --strict-mcp-config,
 // stdin from temp file) are absorbed from claude-remember's verified
 // pattern (see docs/research/2026-05-25-claude-remember-code-dive.md
@@ -180,13 +180,28 @@ export class HaikuViaAnthropicApi extends CompressorBackend {
     const mcpConfigPath = join(sandbox, 'empty-mcp.json');
     writeFileSync(mcpConfigPath, JSON.stringify({ mcpServers: {} }), 'utf8');
 
-    // Build claude --print invocation with the documented sandbox flags.
-    // Empty allowedTools + empty MCP config = tightest possible sandbox;
-    // the sub-Claude can only respond, not act.
+    // Build claude --print invocation with the documented sandbox flags (D-43,
+    // verified against code.claude.com/docs/en/cli-reference, Task 88).
+    //   --tools ""          → disables ALL built-in tools. This is the flag that
+    //                         actually restricts what the sub-Claude can DO ("Use
+    //                         `""` to disable all" per the CLI reference). It is the
+    //                         real sandbox: the model can only emit text.
+    //   --allowed-tools ""  → an AUTO-APPROVE allowlist (tools that run WITHOUT a
+    //                         permission prompt), NOT an availability restriction.
+    //                         Empty = nothing auto-approves; kept as defense-in-depth
+    //                         (redundant once --tools "" removes all tools, harmless).
+    //   --max-turns 1 + empty --mcp-config + --strict-mcp-config → one turn, no MCP
+    //                         tools, so even absent an approver the model can't act.
+    // (Earlier this relied on `--allowed-tools ""` alone with a comment claiming it
+    //  was the sandbox — wrong per primary source: that flag is the allowlist, not
+    //  the restriction. Live exposure was ~nil under --print+--max-turns 1, but the
+    //  flag now matches the stated intent.)
     const args = [
       '--print',
       '--model',
       this._model,
+      '--tools',
+      '',
       '--allowed-tools',
       '',
       '--max-turns',

package/src/conflict-queue.mjs

@@ -111,7 +111,13 @@ export function tokenJaccardSimilarity(a, b) {
 
 const BULLET_LINE_RE = /^- \(([PUL])-([A-Za-z0-9]{8})\)\s+(.+)$/;
 const HEADING_LINE_RE = /^##\s+(.+?)\s*$/;
-const PROVENANCE_RE = /^<!--\s*(.*?)\s*-->\s*$/;
+// Leading `\s*` is load-bearing: scratchpad provenance comments are written
+// INDENTED (`  <!-- … trust: high … -->`) by writeBullet/appendScratchpadBullet.
+// Without the leading-whitespace tolerance, collectExistingBullets failed to
+// parse trust and defaulted EVERY existing bullet to 'medium' — so a new
+// medium fact would wrongly 'supersede' an existing trust:high hand-curated
+// bullet instead of routing to the conflict queue (B-1, surfaced by Task 45).
+const PROVENANCE_RE = /^\s*<!--\s*(.*?)\s*-->\s*$/;
 
 function findSectionRange(lines, sectionTitle) {
   let startIdx = -1;
@@ -244,6 +250,7 @@ export function detectConflicts({
       conflict: true,
       action: 'supersede',
       existingId: best.id,
+      existingText: best.text,
       similarity: best.similarity,
       similarityBackend,
     };

package/src/daily-distill.mjs

@@ -33,6 +33,7 @@ import {
   isCooldownActive,
   touchCooldownMarker,
 } from './cooldown.mjs';
+import { autoDrainQueues } from './auto-drain.mjs';
 
 const DEFAULT_MAX_OUTPUT_BYTES = 4096;
 const SESSIONS_REL = ['context', 'sessions'];
@@ -56,19 +57,17 @@ function buildDistillInstructions(maxOutputBytes) {
     '## Open Questions',
     '- <one bullet per unresolved question, ≤80 chars>',
     '',
-    '## Files Touched',
-    '- path: <relative path> — <verb summary across days>',
-    '',
     '## Active Threads',
     '- <one bullet per active work-in-progress thread, ≤80 chars>',
     '',
     'HARD RULES:',
-    '  1. Preserve every citation ID matching /#[ULP]-[A-Z0-9]{6,8}/ verbatim. Never invent new IDs.',
-    `  2. Total output ≤ ${maxOutputBytes} bytes.`,
-    '  3. If a section has no entries, omit the heading entirely.',
-    '  4. No prose around the headings — only the bulleted list per section.',
-    '  5. Deduplicate aggressively: if the same decision appears across multiple days, list it ONCE.',
-    '  6. Your output goes directly into the next session\'s memory. Do not address the user, do not refer to yourself.',
+    '  1. Every bullet must be grounded in the daily summaries below. Do not infer or add any fact not explicitly present in them. When the summaries show a fact was later corrected, replaced, or reversed, keep ONLY the latest version of that fact — never list the superseded one alongside it (this resolves contradictions, NOT coexisting facts on different points). If unsure, omit it.',
+    '  2. Preserve every citation ID matching /#[ULP]-[A-Z0-9]{6,8}/ verbatim. Never invent new IDs.',
+    `  3. Total output ≤ ${maxOutputBytes} bytes.`,
+    '  4. If a section has no entries, omit the heading entirely.',
+    '  5. No prose around the headings — only the bulleted list per section.',
+    '  6. Deduplicate aggressively: if the same decision appears across multiple days, list it ONCE.',
+    '  7. Your output goes directly into the next session\'s memory. Do not address the user, do not refer to yourself.',
     '',
     '=== BEGIN DAILY SUMMARIES TO CONSOLIDATE ===',
   ].join('\n');
@@ -125,6 +124,7 @@ export async function dailyDistill({
   now,
   cooldownMs = DEFAULT_COOLDOWN_MS,
   maxOutputBytes = DEFAULT_MAX_OUTPUT_BYTES,
+  skipDrain = false,
 } = {}) {
   const ts = now ?? nowIso();
   const date = ts.slice(0, 10);
@@ -143,6 +143,13 @@ export async function dailyDistill({
     return { action: 'skipped', reason: 'no-context-dir', duration_ms: Date.now() - t0 };
   }
 
+  // Auto-drain the project-tier review + conflict queues (v0.2 Phase 2, D-6).
+  // Non-Haiku file IO — runs on EVERY pass regardless of the Haiku cooldown
+  // below, so queues drain even when the distill itself is cooled down.
+  // skipDrain: weeklyCurate calls dailyDistill internally AFTER it already
+  // drained, so it passes skipDrain to avoid a redundant (idempotent) drain.
+  const drained = skipDrain ? null : await autoDrainQueues({ tier: 'P', projectRoot });
+
   // Cooldown gate per design §8.2.
   if (isCooldownActive({ projectRoot, now: ts, cooldownMs })) {
     const duration_ms = Date.now() - t0;
@@ -153,7 +160,7 @@ export async function dailyDistill({
       cost_usd: 0, duration_ms, success: true, skipped_reason: 'cooldown',
     };
     writeDistillLogEntry({ projectRoot, date, entry });
-    return { action: 'skipped', reason: 'cooldown', duration_ms };
+    return { action: 'skipped', reason: 'cooldown', drained, duration_ms };
   }
 
   // Read last 7 days of today-*.md.
@@ -180,7 +187,7 @@ export async function dailyDistill({
         skipped_reason: 'no-input',
       },
     });
-    return { action: 'skipped', reason: 'no-input', duration_ms };
+    return { action: 'skipped', reason: 'no-input', drained, duration_ms };
   }
 
   const buffer = readBuffer(files);
@@ -247,6 +254,7 @@ export async function dailyDistill({
     bytesIn: input_bytes,
     bytesOut: output_bytes,
     sourceDays: files.length,
+    drained,
     duration_ms,
   };
 }

package/src/doctor.mjs

@@ -44,6 +44,7 @@ import { basename, join } from 'node:path';
 import { nowIso } from './audit-log.mjs';
 import { detectStaleLocks } from './lock-discipline.mjs';
 import { cronSentinelPath } from './lazy-compress.mjs';
+import { getNativeAutoMemoryState } from './native-memory.mjs';
 
 const TWO_DAYS_MS = 2 * 24 * 60 * 60 * 1000;
 const THREE_DAYS_MS = 3 * 24 * 60 * 60 * 1000;
@@ -188,12 +189,15 @@ function hc2Hooks({ projectRoot }) {
 function hc3DistillFreshness({ projectRoot, now }) {
   const recentPath = join(projectRoot, ...RECENT_MD_REL);
   if (!existsSync(recentPath)) {
+    // Not a failure: on a fresh project there's nothing distilled yet, and
+    // when there is, the lazy-on-read path runs the distill at SessionStart
+    // (or `cmk daily-distill`). "Stale recent.md" below IS a real fail; a
+    // never-built one is just "not yet" — mirror HC-5's skip-on-fresh.
     return {
       id: 'HC-3',
       name: 'Daily distill is fresh (≤2 days)',
-      status: 'fail',
-      message: 'context/sessions/recent.md missing — distill never ran',
-      recoveryCommand: 'cmk daily-distill',
+      status: 'skip',
+      message: 'recent.md not built yet — nothing to distill. Runs automatically (lazy-on-read at SessionStart, or `cmk daily-distill`) once there is session content.',
     };
   }
   let mtimeMs;
@@ -231,19 +235,22 @@ function hc3DistillFreshness({ projectRoot, now }) {
 function hc4Transcripts({ projectRoot, now }) {
   const transcriptsDir = join(projectRoot, ...TRANSCRIPTS_REL);
   if (!existsSync(transcriptsDir)) {
+    // Fresh project, never had a Claude Code session here → nothing to fire
+    // yet. Skip, don't fail (the dir + first transcript appear on the first turn).
     return {
       id: 'HC-4',
       name: 'Transcripts firing (≤3 days)',
-      status: 'fail',
-      message: 'context/transcripts/ missing — kit not capturing turn transcripts',
-      recoveryCommand: 'check that this project is the primary cwd in Claude Code, then reopen the project',
+      status: 'skip',
+      message: 'no transcripts yet — they appear after your first Claude Code turn in this project.',
     };
   }
   const nowMs = new Date(now ?? nowIso()).getTime();
   const cutoffMs = nowMs - THREE_DAYS_MS;
+  let totalCount = 0;
   let recentCount = 0;
   for (const name of readdirSync(transcriptsDir)) {
     if (!/\.md$/.test(name)) continue;
+    totalCount += 1;
     try {
       const mtimeMs = statSync(join(transcriptsDir, name)).mtimeMs;
       if (mtimeMs >= cutoffMs) recentCount += 1;
@@ -251,12 +258,24 @@ function hc4Transcripts({ projectRoot, now }) {
       // skip unreadable
     }
   }
+  if (totalCount === 0) {
+    // Dir exists (scaffolded) but no transcripts captured yet → still "not
+    // yet", not a failure.
+    return {
+      id: 'HC-4',
+      name: 'Transcripts firing (≤3 days)',
+      status: 'skip',
+      message: 'no transcripts yet — they appear after your first Claude Code turn in this project.',
+    };
+  }
   if (recentCount === 0) {
+    // Transcripts EXIST but none recent → the kit was capturing and stopped.
+    // That IS a real signal (the Stop hook may not be firing here).
     return {
       id: 'HC-4',
       name: 'Transcripts firing (≤3 days)',
       status: 'fail',
-      message: 'no transcripts within 3 days — likely this project is not Claude Code\'s primary cwd',
+      message: 'transcripts exist but none within 3 days — the Stop hook may have stopped firing (is this project Claude Code\'s primary cwd?)',
       recoveryCommand: 'reopen this project as the primary cwd in Claude Code',
     };
   }
@@ -318,16 +337,28 @@ function hc5IndexConsistency({ projectRoot }) {
       recoveryCommand: 'cmk reindex',
     };
   }
-  // M2 fix (skill-review 2026-05-28): constrain the regex to fact-file
-  // id shapes (`[PUL]-XXXXXXXX.md`) so unrelated markdown links inside
-  // INDEX.md (e.g., "see also design.md") don't false-positive as fact
-  // file references. Mirrors the kit's ID_PATTERN base32 alphabet
-  // (excluding 0/O/1/l/I/8).
+  // Fact-file references in INDEX.md are markdown LINK TARGETS whose filename
+  // follows the kit's `<type>_<slug>.md` convention (e.g. feedback_layered.md) —
+  // that's what `cmk reindex`'s formatIndexLine writes: `[slug](type_slug.md)`.
+  // Match the link target's *.md basename, THEN keep only fact-file-shaped names.
+  //
+  // Two false-positives this must avoid (both real):
+  //   1. id-shaped names — the pre-Task-85 regex matched `[PUL]-XXXXXXXX.md`,
+  //      which the kit NEVER generates, so HC-5 false-FAILED "missing" on every
+  //      real fact the moment one existed (lior-test-7 2026-06-03).
+  //   2. non-fact links — a broad `](...md)` match also catches the scaffold's
+  //      own example `- [type] [Title](filename.md)` (inside an HTML comment) and
+  //      any prose link like `(design.md)`, which would false-FAIL "stale" on a
+  //      FRESH install (skill-review 2026-06-03). The `<type>_<slug>` shape
+  //      (a `type_` underscore prefix) excludes `filename.md` / `design.md` /
+  //      `0001.md` while matching every real fact file.
+  const FACT_FILE_RE = /^[a-z]+_[a-z0-9][a-z0-9-]*\.md$/i;
   const indexEntries = new Set();
-  const re = /\b([PUL]-[A-Za-z2-9]{8})\.md\b/g;
+  const re = /\]\(([^)]+\.md)\)/g;
   let m;
   while ((m = re.exec(indexText)) !== null) {
-    indexEntries.add(m[1] + '.md');
+    const fname = m[1].split(/[\\/]/).pop(); // basename, tolerate ./ or path-prefixed links
+    if (fname && fname !== 'INDEX.md' && FACT_FILE_RE.test(fname)) indexEntries.add(fname);
   }
   const factSet = new Set(factFiles);
   const inFactsNotIndex = [...factSet].filter((f) => !indexEntries.has(f));
@@ -362,12 +393,15 @@ function hc6CronRegistered({ projectRoot }) {
       message: 'cron-registered sentinel present',
     };
   }
+  // Cron is OPTIONAL by design (README + design §… the lazy-on-read fallback
+  // compresses at SessionStart without any scheduler). Absence is therefore a
+  // SKIP, not a FAIL — flagging an optional, working-by-fallback feature as a
+  // failure made a healthy fresh install read as broken.
   return {
     id: 'HC-6',
     name: 'Cron jobs registered with host scheduler',
-    status: 'fail',
-    message: 'no cron-registered sentinel — kit will use lazy-on-read fallback (still functional, slower)',
-    recoveryCommand: 'cmk register-crons',
+    status: 'skip',
+    message: 'cron not registered (optional) — using the lazy-on-read fallback (compresses at SessionStart). Run `cmk register-crons` for scheduled background compression.',
   };
 }
 
@@ -443,6 +477,13 @@ function hc8NativeAutoMemory({ projectRoot, now }) {
   // NOW" checks, not trend analysis. Trend logging is a v0.1.x
   // candidate (would require append + rotation or a separate
   // history.ndjson file).
+  // ADR-0011 / Task 60: the project's committable `autoMemoryEnabled` setting
+  // is what actually governs native memory going forward. Fold it into both
+  // the snapshot log (Door 4 observability) and the message so the
+  // `cmk disable-native-memory` opt-in is DISCOVERABLE here, not just at install.
+  const { state: settingState } = getNativeAutoMemoryState({ projectRoot });
+  entry.setting_state = settingState;
+
   const logPath = join(projectRoot, ...NATIVE_MEMORY_LOG_REL);
   try {
     mkdirSync(join(projectRoot, ...LOCKS_REL), { recursive: true });
@@ -450,16 +491,26 @@ function hc8NativeAutoMemory({ projectRoot, now }) {
   } catch {
     // best-effort
   }
+
+  let message;
+  if (settingState === 'disabled') {
+    // The user opted out — native won't write here regardless of any old files.
+    message = 'Anthropic auto-memory DISABLED for this project via .claude/settings.json — the kit is the sole memory layer.';
+  } else if (entry.active === true) {
+    // Native is writing AND not disabled → both layers run (context bloat).
+    // Surface the one-command opt-out (the coexistence choice, discoverable late).
+    message = `Anthropic auto-memory ACTIVE (${entry.file_count} files; last: ${entry.last_modified ?? 'unknown'}) — running ALONGSIDE the kit (both inject at session start). Run \`cmk disable-native-memory\` to use one lean layer.`;
+  } else if (entry.active === false) {
+    message = 'Anthropic auto-memory not active for this project (kit is the sole memory source).';
+  } else {
+    message = 'Anthropic auto-memory state unknown (directory unreadable).';
+  }
+
   return {
     id: 'HC-8',
     name: 'Native Anthropic Auto Memory status detected',
     status: 'pass',
-    message:
-      entry.active === true
-        ? `Anthropic auto-memory ACTIVE (${entry.file_count} files; last: ${entry.last_modified ?? 'unknown'})`
-        : entry.active === false
-          ? 'Anthropic auto-memory not active for this project (kit is the sole memory source)'
-          : 'Anthropic auto-memory state unknown (directory unreadable)',
+    message,
   };
 }
 

package/src/forget.mjs

@@ -26,6 +26,7 @@ import {
 import { parse, format } from './frontmatter.mjs';
 import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult, notFoundResult } from './result-shapes.mjs';
+import { findBulletScratchpad } from './bullet-lookup.mjs';
 
 // Layer-2 review: PR-1 rejected \n / \r / : in the `reason` field as a
 // minimum fix for the naive serializer (finding B2). PR-2's frontmatter.mjs
@@ -208,6 +209,19 @@ export function forget(opts = {}) {
     : resolveByQuery(idOrQuery, { projectRoot, userDir });
 
   if (resolved.matches.length === 0) {
+    // If the id is actually a scratchpad BULLET (the `cmk search` id mix-up —
+    // search lists bullet ids too, but forget tombstones FACTS), say so instead
+    // of the flat "no matching fact".
+    const bulletIn = ID_PATTERN.test(idOrQuery)
+      ? findBulletScratchpad(idOrQuery, { projectRoot, userDir })
+      : null;
+    if (bulletIn) {
+      return notFoundResult({
+        errors: [
+          `'${idOrQuery}' is a scratchpad bullet in ${bulletIn}, not a fact — \`cmk forget\` tombstones facts in context/memory/. A high-trust bullet becomes forgettable by this same id once it graduates to a fact (under cap pressure / at session end); a low/medium one ages out via consolidation. To remove it now, edit ${bulletIn} directly.`,
+        ],
+      });
+    }
     return notFoundResult({
       errors: [`no matching fact for "${idOrQuery}"`],
     });

package/src/graduate-session.mjs

@@ -0,0 +1,65 @@
+// Proactive SessionEnd graduation sweep (Task 94.3, D-61 / design §19).
+//
+// The reactive relief inside appendScratchpadBullet only fires when a write
+// triggers cap pressure. This sweep runs the same relief OUTSIDE the append path,
+// across every fact-bearing scratchpad, so each scratchpad's INJECTED slice stays
+// under its load-cap even in a read-only session — and low/medium bullets that
+// AGED past the 14-day stale window between sessions get caught.
+//
+// Composition (the §6.8/§7.1 disjoint-input rule): this is invoked by
+// runSessionEndTasks SEQUENTIALLY, AFTER the concurrent compress+persona block —
+// because autoPersona WRITES the user-tier persona scratchpads (USER/HABITS/
+// LESSONS) and this READS+rewrites them, so the two must not overlap. Running
+// after means the sweep sees the freshly-promoted persona, then trims overflow.
+// It is pure local file I/O (no Haiku/network), so it adds <<1s on top of the
+// ~50s concurrent block — no SessionEnd hook-ceiling risk.
+
+import { sweepScratchpadForCapRelief } from './scratchpad.mjs';
+
+// The fact-bearing scratchpads, per tier. The L tier (machine-paths/overrides) is
+// machine-specific config, not durable facts — never graduated (matches the
+// `tier === 'P' || tier === 'U'` gate in the reactive path).
+const GRADUATION_TARGETS = Object.freeze([
+  { tier: 'P', scratchpad: 'MEMORY.md' },
+  { tier: 'P', scratchpad: 'SOUL.md' },
+  { tier: 'U', scratchpad: 'USER.md' },
+  { tier: 'U', scratchpad: 'HABITS.md' },
+  { tier: 'U', scratchpad: 'LESSONS.md' },
+]);
+
+/**
+ * Sweep every fact-bearing scratchpad, graduating overflow so each stays under
+ * its load-cap. Best-effort: a failure on one scratchpad is captured as an
+ * `error` result and never aborts the rest (a SessionEnd hook must never throw).
+ *
+ * @param {object} opts
+ * @param {string} opts.projectRoot - resolved project root.
+ * @param {string} opts.userDir - user-tier root.
+ * @param {string} [opts.now] - ISO timestamp override (tests).
+ * @param {object} [opts.settings] - test-injected cap override.
+ * @returns {{results: object[], totalGraduated: number, totalConsolidated: number}}
+ */
+export function graduateAllScratchpads({ projectRoot, userDir, now, settings } = {}) {
+  const results = [];
+  for (const t of GRADUATION_TARGETS) {
+    try {
+      results.push(
+        sweepScratchpadForCapRelief({ ...t, projectRoot, userDir, now, settings }),
+      );
+    } catch (err) {
+      results.push({
+        tier: t.tier,
+        scratchpad: t.scratchpad,
+        action: 'error',
+        error: err?.message ?? String(err),
+        bulletsConsolidated: 0,
+        bulletsGraduated: 0,
+        graduatedIds: [],
+        bytes: 0,
+      });
+    }
+  }
+  const totalGraduated = results.reduce((s, r) => s + (r.bulletsGraduated || 0), 0);
+  const totalConsolidated = results.reduce((s, r) => s + (r.bulletsConsolidated || 0), 0);
+  return { results, totalGraduated, totalConsolidated };
+}