@lh8ppl/claude-memory-kit 0.3.1 → 0.3.3

package/README.md

@@ -1,3 +1,10 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/LH8PPL/claude-memory-kit/main/docs/public/assets/wordmark-dark.svg">
+    <img src="https://raw.githubusercontent.com/LH8PPL/claude-memory-kit/main/docs/public/assets/wordmark.svg" alt="claude-memory-kit" width="340">
+  </picture>
+</p>
+
 # @lh8ppl/claude-memory-kit
 
 **`cmk`** — the CLI for [claude-memory-kit](https://github.com/LH8PPL/claude-memory-kit), a per-project, in-repo memory system for [Claude Code](https://docs.claude.com/en/docs/claude-code). It fixes Claude's per-session amnesia so you don't have to re-tell the backstory every time you start a new session.
@@ -40,11 +47,13 @@ cmk doctor         # verify, then restart Claude Code
 Inside Claude Code:
 
 ```text
-/plugin marketplace add LH8PPL/claude-memory-kit
-/plugin install claude-memory-kit
+/plugin marketplace add LH8PPL/claude-memory-kit   # add this repo as a plugin source (once per machine)
+/plugin install claude-memory-kit                  # install the global machinery — hooks + skills (once per machine)
+cd ~/my-project                                    # the project you want memory in — bootstrap scaffolds into the CURRENT dir
+/claude-memory-kit:bootstrap                        # scaffold this project's context/ memory tree (once per project)
 ```
 
-Then say *"bootstrap the memory system"* to scaffold this project's `context/`. The plugin bundles the hooks + the `bootstrap`, `memory-write`, and `memory-search` skills, so it's complete without the npm CLI (add the CLI later only if you want `cmk search` / `cmk doctor` / cron).
+The first two commands are **global** (per machine); `bootstrap` is **per project** — run it again (after a `cd`) in each project. The plugin bundles the hooks + the `bootstrap`, `memory-write`, and `memory-search` skills, so it's complete without the npm CLI (add the CLI later only if you want `cmk search` / `cmk doctor` / cron).
 
 ## CLI
 
@@ -55,7 +64,7 @@ Most-used commands (full list via `cmk --help`):
 | `cmk install` | Scaffold `context/` + the `memory-write`/`memory-search` skills + `.gitignore` + CLAUDE.md block + wire hooks (`--no-hooks` for scaffold-only) |
 | `cmk doctor` | Run HC-1..HC-8 health checks, surface repair commands |
 | `cmk repair --hooks` / `--locks` / `--index` / `--all` | Idempotent self-repair |
-| `cmk search "<query>" [--mode keyword\|semantic\|hybrid] [--scope facts\|transcripts]` | Search memory — by meaning with the embedder (hybrid default after `--with-semantic`); `--scope transcripts` = the raw session record |
+| `cmk search "<query>" [--mode keyword\|semantic\|hybrid] [--scope facts\|transcripts\|decisions]` | Search memory — by meaning with the embedder (hybrid default after `--with-semantic`); `--scope transcripts` = the raw session record; `--scope decisions` = the decision journal (history / "what did we reject") |
 | `cmk get <id…>` / `cmk timeline <id>` / `cmk cite <id>` / `cmk recent-activity` | Read the index back — full fact bodies + provenance, sequential context around an observation, a canonical citation link, recent changes (the CLI side of the `mk_*` MCP read tools) |
 | `cmk roll --scope now\|today\|recent` | Manually trigger a compression pipeline |
 | `cmk register-crons [--dry-run] [--unregister]` | Register daily + weekly jobs with cron / launchd / Task Scheduler |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lh8ppl/claude-memory-kit",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "cmk — the CLI for claude-memory-kit. Per-project, in-repo memory system for Claude Code.",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "better-sqlite3": "^12.10.0",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^4.2.0",
     "sqlite-vec": "^0.1.9",
     "zod": "^4.4.3"
   },

package/src/auto-extract.mjs

@@ -53,6 +53,7 @@ import { hashContent } from './content-hash.mjs';
 import { memoryWrite } from './memory-write.mjs';
 import { writeFact } from './write-fact.mjs';
 import { buildRichFactBody, slugifyFact } from './rich-fact.mjs';
+import { sanitizeForTitle } from './sanitize.mjs';
 import { HaikuTimeoutError } from './compressor.mjs';
 import { pidIsAlive } from './lock-discipline.mjs';
 import { nowIso } from './audit-log.mjs';
@@ -638,9 +639,16 @@ function routeMedium({ candidate, projectRoot, ts }) {
 // Direct-to-fact-store (NOT the review queue the terse medium-trust path uses):
 // the point of Task 103 is AUTOMATIC native-parity capture — native writes its
 // fact files with no approval step, so parity requires the same. The fact store
-// is searchable-but-not-full-trust-injected, writeFact already screens every
-// write (home-path sanitize + Poison_Guard + schema + INDEX/reindex), and a
-// later explicit `cmk remember` (trust:high) supersedes. See design §6.4.
+// is searchable-but-not-full-trust-injected, writeFact screens the body +
+// frontmatter (Poison_Guard + home-path sanitize + schema + INDEX/reindex), and
+// a later explicit `cmk remember` (trust:high) supersedes. See design §6.4.
+//
+// CAVEAT (F-V0.3.3-2): writeFact does NOT sanitize the SLUG/filename — the slug
+// is `slugifyFact(title)` derived HERE, before writeFact runs. So the title MUST
+// be routed through sanitizeForTitle first, or a home path in Haiku's candidate
+// title (auto-extract runs every turn, no user action) leaks the username into a
+// COMMITTED filename. This was the same bug as cmk remember — the old comment
+// here wrongly assumed "writeFact already sanitizes" the whole write.
 //
 // trust:medium / write_source:auto-extract marks it as a Haiku synthesis
 // (proposal-grade), below the explicit-high tier. The body is built by the SAME
@@ -652,11 +660,14 @@ function routeRichFact({ candidate, projectRoot, ts }) {
     why: candidate.why,
     how: candidate.how,
   });
+  // Sanitize the title BEFORE deriving the slug (F-V0.3.3-2) — writeFact won't
+  // catch a home path in the slug/filename. One helper, same as cmk remember.
+  const title = sanitizeForTitle(candidate.title);
   return writeFact({
     tier: 'P',
     type: candidate.type,
-    slug: slugifyFact(candidate.title),
-    title: candidate.title,
+    slug: slugifyFact(title),
+    title,
     body,
     writeSource: 'auto-extract',
     trust: 'medium',

package/src/decisions-journal.mjs

@@ -0,0 +1,223 @@
+// The append-only decision journal — context/DECISIONS.md (Task 147, D-161).
+//
+// A chronological, human-readable page of every decision + its why. The VIEW
+// the kit was missing: decisions are captured as facts but scattered across N
+// per-fact files with no chronological decision page (cmk search is pull, not
+// browse; MEMORY.md is bounded + rolls). This is the squad `decisions.md` /
+// our own DECISION-LOG.md equivalent, made automatic.
+//
+// LIFECYCLE — APPEND-ONLY, never regenerated, never parked (D-161):
+//   - This is NOT a derived view like INDEX.md. Regenerating from live facts
+//     would silently ERASE superseded/forgotten decisions — rewriting history
+//     to look like the current state was always obvious (the exact failure the
+//     decision-trail-preservation rule exists to prevent).
+//   - A decision journal is unbounded by design: old decisions are the MOST
+//     valuable part (they explain why the codebase is shaped as it is), so the
+//     MEMORY.md rolling-window must NOT apply.
+//   - Mechanics: new decision → appended; tombstoned → its entry MARKED
+//     retracted IN PLACE (never removed); every pre-existing entry survives
+//     every update.
+//
+// The update is triggered like a derived view (runs where reindex runs, so the
+// journal stays current) but its WRITE LOGIC is append-only — the file is the
+// accumulator, the facts are only the trigger. Each entry carries a stable
+// machine marker `<!-- decision:P-XXXXXXXX -->` so the updater knows which ids
+// are already journaled + which entries to annotate, without parsing prose
+// (and so a human can freely add their own prose between entries — preserved).
+//
+// v0.3.2 scope: explicit signals only (capture appends; forget marks retracted;
+// explicit supersession annotates). AUTOMATIC semantic contradiction-detection
+// is deferred to F-D / Task 95.
+
+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';
+
+export const DECISIONS_HEADER =
+  '# Decisions\n\n' +
+  '> Append-only decision journal — every decision the kit captured, in order, with its why.\n' +
+  '> Maintained by claude-memory-kit (`cmk digest`). Superseded/retracted entries stay (the trail is the point).';
+
+// Only this fact type is a "decision" in the kit taxonomy (the project/state
+// category — what project-memory's decisions.md and our DECISION-LOG track).
+const DECISION_TYPE = 'project';
+
+const markerFor = (id) => `<!-- decision:${id} -->`;
+const RETRACT_TAG = '_(retracted';
+
+/** The yyyy-mm-dd slice of an ISO timestamp, or the raw value if unparseable. */
+function dateOnly(iso) {
+  if (typeof iso !== 'string') return 'unknown-date';
+  const m = iso.match(/^(\d{4}-\d{2}-\d{2})/);
+  return m ? m[1] : iso;
+}
+
+/**
+ * Render ONE journal entry for a decision fact. The machine marker lets the
+ * updater dedup + annotate; the human-readable lines are Title / date / Why / id.
+ *
+ * @param {{id:string,title:string,createdAt?:string,why?:string|null}} f
+ * @returns {string} the entry block (no trailing newline)
+ */
+export function buildDecisionEntry(f) {
+  const date = dateOnly(f.createdAt);
+  const lines = [
+    markerFor(f.id),
+    `### ${f.title}`,
+    `**When:** ${date} · **Fact:** \`${f.id}\``,
+  ];
+  if (f.why && String(f.why).trim()) {
+    lines.push(`**Why:** ${String(f.why).trim()}`);
+  }
+  return lines.join('\n');
+}
+
+// The kit's id matcher, DERIVED from the canonical ID_PATTERN (tier-paths.mjs)
+// so the base32 alphabet lives in exactly ONE place and can't drift. The
+// original bug: this module hardcoded `[A-Z2-9]` (uppercase only), but the real
+// alphabet includes a lowercase `a` — so any id containing `a` never matched
+// "already journaled" → re-appended on EVERY digest run (the cut-gate find).
+// Strip the `^…$` anchors to embed the pattern inside larger regexes.
+const ID_CHARS = ID_PATTERN.source.replace(/^\^/, '').replace(/\$$/, '');
+
+/** ids already present in the journal body (by their machine marker). */
+function journaledIds(content) {
+  const ids = new Set();
+  const re = new RegExp(`<!-- decision:(${ID_CHARS}) -->`, 'g');
+  let m;
+  while ((m = re.exec(content)) !== null) ids.add(m[1]);
+  return ids;
+}
+
+/**
+ * Append-only journal update (D-161). Pure: content in → content out.
+ *
+ * @param {object} a
+ * @param {string}   a.existingContent  current DECISIONS.md (‘’ if absent)
+ * @param {Array}    a.facts            live decision-class facts ({id,type,title,createdAt,why})
+ * @param {Set<string>} a.tombstonedIds ids whose fact has been forgotten
+ * @param {string}   a.now             ISO timestamp for retraction stamps
+ * @returns {string} the new DECISIONS.md content
+ */
+export function updateDecisionsJournal({ existingContent = '', facts = [], tombstonedIds = new Set(), now }) {
+  let content = existingContent.trim() === '' ? DECISIONS_HEADER + '\n' : existingContent;
+  const already = journaledIds(content);
+
+  // 1) Append entries for decision-class facts not yet journaled.
+  const newEntries = [];
+  for (const f of facts) {
+    if (f.type !== DECISION_TYPE) continue; // only decisions
+    if (already.has(f.id)) continue; // already journaled — never duplicate
+    newEntries.push(buildDecisionEntry(f));
+    already.add(f.id);
+  }
+  if (newEntries.length > 0) {
+    if (!content.endsWith('\n')) content += '\n';
+    content += '\n' + newEntries.join('\n\n') + '\n';
+  }
+
+  // 2) Mark retracted (in place) any journaled entry whose fact is now
+  //    tombstoned and not already marked. Never removes the entry.
+  const stamp = dateOnly(now);
+  for (const id of tombstonedIds) {
+    const marker = markerFor(id);
+    const idx = content.indexOf(marker);
+    if (idx === -1) continue; // not journaled — nothing to retract
+    // Bound the search to THIS entry's span — up to the next decision marker
+    // (or end-of-file). Prevents a malformed/hand-edited entry with no heading
+    // 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);
+    if (headingStart === -1 || headingStart >= spanEnd) continue;
+    const headingEnd = content.indexOf('\n', headingStart);
+    if (headingEnd === -1) continue;
+    // Already retracted? (the note sits right after the heading)
+    const afterHeading = content.slice(headingEnd + 1, headingEnd + 1 + RETRACT_TAG.length);
+    if (afterHeading === RETRACT_TAG) continue;
+    const note = `${RETRACT_TAG} ${stamp})_`;
+    content = content.slice(0, headingEnd + 1) + note + '\n' + content.slice(headingEnd + 1);
+  }
+
+  if (!content.endsWith('\n')) content += '\n';
+  return content;
+}
+
+// --- File-IO orchestration (the impure shell over the pure core) ----------
+
+// Leading indent is [ \t]* (NOT \s*) so it can't match the newline the
+// (?:^|\n) anchor already consumed — that overlap is the backtracking
+// ambiguity SonarCloud flags as ReDoS. Disjoint character classes = linear.
+const RICH_WHY_RE = /(?:^|\n)[ \t]*\*\*Why:\*\*[ \t]*([^\n]+)/;
+
+/** Read decision-class facts (type:project) from the project tier. */
+function readProjectDecisionFacts(projectRoot) {
+  const dir = join(projectRoot, 'context', 'memory');
+  const out = [];
+  if (!existsSync(dir)) return out;
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.md') || name === 'INDEX.md') continue;
+    try {
+      const { frontmatter, body } = parseFrontmatter(readFileSync(join(dir, name), 'utf8'));
+      if (!frontmatter?.id || frontmatter.type !== DECISION_TYPE) continue;
+      if (frontmatter.deleted_at) continue;
+      const whyMatch = String(body ?? '').match(RICH_WHY_RE);
+      out.push({
+        id: frontmatter.id,
+        type: frontmatter.type,
+        title: frontmatter.title ?? frontmatter.id,
+        createdAt: frontmatter.created_at ?? null,
+        why: whyMatch ? whyMatch[1].trim() : null,
+      });
+    } catch {
+      // unparseable file — reindex/HC-4 own that class; the journal skips it
+    }
+  }
+  // Stable chronological order (oldest first) so appends read like a timeline.
+  out.sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+  return out;
+}
+
+/** ids of forgotten facts (tombstone archive). */
+function readTombstonedIds(projectRoot) {
+  const ids = new Set();
+  const dir = join(projectRoot, 'context', 'memory', 'archive', 'tombstones');
+  if (!existsSync(dir)) return ids;
+  for (const name of readdirSync(dir)) {
+    const m = name.match(new RegExp(`^(${ID_CHARS})\\.md$`));
+    if (m) ids.add(m[1]);
+  }
+  return ids;
+}
+
+/**
+ * Read → append-only update → write context/DECISIONS.md. Idempotent: a run
+ * with nothing new is a no-op write (same bytes). Best-effort: never throws
+ * into the caller (a journal failure must not break a capture/read path).
+ *
+ * @returns {{written:boolean, path:string, appended:number}|{written:false,error:string}}
+ */
+export function syncDecisionsJournal({ projectRoot, now } = {}) {
+  try {
+    const path = join(projectRoot, 'context', 'DECISIONS.md');
+    const existingContent = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    const facts = readProjectDecisionFacts(projectRoot);
+    const tombstonedIds = readTombstonedIds(projectRoot);
+    const before = existingContent;
+    const next = updateDecisionsJournal({
+      existingContent,
+      facts,
+      tombstonedIds,
+      now: now ?? new Date().toISOString(),
+    });
+    if (next !== before) {
+      writeFileSync(path, next, 'utf8');
+      return { written: true, path, appended: next.length - before.length };
+    }
+    return { written: false, path, appended: 0 };
+  } catch (err) {
+    return { written: false, error: err?.message ?? String(err) };
+  }
+}

package/src/digest.mjs

@@ -0,0 +1,89 @@
+// `cmk digest` — a regenerated, readable render of everything the kit currently
+// knows (Task 147, D-132). Facts by type + the persona + active threads, as one
+// markdown page. The README-demo artifact.
+//
+// REGENERATED (not append-only): unlike DECISIONS.md (the permanent journal),
+// the digest is a CURRENT-KNOWLEDGE snapshot — it should reflect only what
+// exists now, so it is rebuilt on every invocation (the INDEX.md lifecycle,
+// correct here). The two surfaces differ on purpose: digest = "what do we know
+// now", DECISIONS.md = "what did we decide over time" (D-161).
+//
+// Read-only by contract: pure reads over the fact archive + scratchpads. The
+// `--decisions` flag also triggers the DECISIONS.md journal sync (the one
+// mutation, delegated to the append-only writer).
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseFrontmatter } from './frontmatter.mjs';
+
+const TYPE_ORDER = ['project', 'feedback', 'reference', 'user'];
+const TYPE_LABEL = {
+  project: 'Decisions & project state',
+  feedback: 'Working-style & preferences',
+  reference: 'References',
+  user: 'About the user',
+};
+
+function readFacts(projectRoot) {
+  const dir = join(projectRoot, 'context', 'memory');
+  const facts = [];
+  if (!existsSync(dir)) return facts;
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.md') || name === 'INDEX.md') continue;
+    try {
+      const { frontmatter } = parseFrontmatter(readFileSync(join(dir, name), 'utf8'));
+      if (!frontmatter?.id || frontmatter.deleted_at) continue;
+      facts.push({
+        id: frontmatter.id,
+        type: frontmatter.type ?? 'unknown',
+        title: frontmatter.title ?? frontmatter.id,
+        trust: frontmatter.trust ?? 'unknown',
+        createdAt: frontmatter.created_at ?? null,
+      });
+    } catch {
+      // unparseable — reindex/HC-4 own that class
+    }
+  }
+  return facts;
+}
+
+/**
+ * Build the digest markdown from facts (pure — exported for testing).
+ * @param {Array} facts
+ * @param {{now?:string}} [opts]
+ */
+export function buildDigest(facts, { now } = {}) {
+  const stamp = (now ?? new Date().toISOString()).slice(0, 10);
+  const lines = [`# Memory digest — ${stamp}`, ''];
+  if (facts.length === 0) {
+    lines.push('_Memory is empty — capture starts as you work._', '');
+    return lines.join('\n');
+  }
+  lines.push(`${facts.length} fact(s) in project memory.`, '');
+
+  const byType = new Map();
+  for (const f of facts) {
+    if (!byType.has(f.type)) byType.set(f.type, []);
+    byType.get(f.type).push(f);
+  }
+  const orderedTypes = [
+    ...TYPE_ORDER.filter((t) => byType.has(t)),
+    ...[...byType.keys()].filter((t) => !TYPE_ORDER.includes(t)),
+  ];
+  for (const type of orderedTypes) {
+    const group = byType.get(type).slice().sort((a, b) => String(a.createdAt).localeCompare(String(b.createdAt)));
+    lines.push(`## ${TYPE_LABEL[type] ?? type} (${group.length})`, '');
+    for (const f of group) {
+      const date = String(f.createdAt ?? '').slice(0, 10) || '—';
+      lines.push(`- **${f.title}** · \`${f.id}\` · ${f.trust} · ${date}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+/** Read facts + render the digest for a project (read-only). */
+export function digest({ projectRoot, now } = {}) {
+  const facts = readFacts(projectRoot);
+  return buildDigest(facts, { now });
+}

package/src/forget.mjs

@@ -172,6 +172,12 @@ function scrubAllScratchpads(tierRoot, id) {
     if (!entry.isFile()) continue;
     if (!entry.name.endsWith('.md')) continue;
     if (entry.name === 'INDEX.md') continue;
+    // DECISIONS.md is the APPEND-ONLY decision journal (Task 147 / D-161), NOT
+    // a scratchpad — forget must NOT strip its id-bearing lines (the marker +
+    // **Fact:** line). The journal sync marks the entry RETRACTED in place
+    // instead (preserving the trail). Scrubbing it here would delete the
+    // entry's marker and break the retract-in-place path (composition bug).
+    if (entry.name === 'DECISIONS.md') continue;
     const p = join(tierRoot, entry.name);
     const r = scrubScratchpadFile(p, id);
     if (r.changed) edits.push({ path: p, removed: r.removed });

package/src/import-claude-md.mjs

@@ -32,7 +32,7 @@ import { appendAuditEntry, nowIso, REASON_CODES } from './audit-log.mjs';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
 import { writeFact } from './write-fact.mjs';
 import { slugifyFact } from './rich-fact.mjs';
-import { sanitizeHomePaths } from './sanitize.mjs';
+import { sanitizeHomePaths, sanitizeForTitle } from './sanitize.mjs';
 import { parse as parseFrontmatter } from './frontmatter.mjs';
 
 const DEFAULT_FILE = 'CLAUDE.md';
@@ -280,7 +280,12 @@ export async function importClaudeMd({
   // absolute --file argument (the D-51 name-privacy class).
   const sourceFileField = sanitizeHomePaths(fileRel);
   for (const p of proposals) {
-    const title = p.text.split('\n')[0].slice(0, 80);
+    // Sanitize BEFORE deriving the title/slug (F-V0.3.3-2) — p.text is the RAW
+    // rule text (the `sanitized` above feeds only the dedup key/id), and the
+    // slug becomes the committed filename, which writeFact won't sanitize. A
+    // CLAUDE.md rule mentioning C:\Users\you\ would otherwise leak the username
+    // into the imported fact's filename. Same one helper as the other slug sites.
+    const title = sanitizeForTitle(p.text).split('\n')[0].slice(0, 80);
     let slug = slugifyFact(title);
     if (usedSlugs.has(`${p.type}/${slug}`)) slug = `${slug}-l${p.line}`;
     usedSlugs.add(`${p.type}/${slug}`);

package/src/index-rebuild.mjs

@@ -295,6 +295,40 @@ function parseSource(source, { projectRoot, userDir }) {
 
 // --- DB write helpers -------------------------------------------------
 
+// Bug 1 (2026-06-16, fact P-UCG4RKNL): the kit dual-writes a fact to BOTH the
+// MEMORY.md scratchpad bullet AND its granular archive file, both carrying the
+// SAME content-addressed id. `observations.id` is a global PRIMARY KEY, so a
+// plain INSERT of the second source's row collided (`UNIQUE constraint failed:
+// observations.id`) and aborted the whole reindex. The fix is id-keyed upsert
+// with deterministic ARCHIVE-BEATS-SCRATCHPAD precedence — validated against
+// three markdown-first analogs that all key replacement on the id, never the
+// file (TencentDB `ON CONFLICT(record_id) DO UPDATE`; basic-memory
+// resolve-permalink precedence + partial unique index; memweave content-hash
+// dedup). See docs/research/2026-06-16-index-uniqueness-id-vs-file-scoped-delete.md.
+//
+// Two precedence-keyed paths, order-INDEPENDENT (the source walk order must not
+// change the surviving row):
+//   - fact (granular archive = the canonical Why/How home) → explicit
+//     DELETE-by-id then INSERT: always wins, overwriting any scratchpad row for
+//     the id.
+//   - scratchpad (the hot working-copy bullet) → ON CONFLICT(id) DO NOTHING:
+//     inserts only when no row exists yet; never overwrites a fact row.
+// Whichever is walked first, the fact row is the one that survives.
+//
+// FTS5 CORRECTNESS (the self-review catch): the fact path uses an explicit
+// DELETE-by-id, NOT `INSERT OR REPLACE`. `observations_fts` is an
+// external-content FTS5 table whose only safe delete path is the
+// `obs_after_delete` trigger firing the 'delete' SENTINEL with the OLD row's
+// column values (index-db.mjs §4.4.3 comment). `INSERT OR REPLACE` reuses the
+// conflicting row's rowid, so its internal delete+insert leaves the OLD
+// scratchpad body orphaned in the FTS index (it keeps MATCH-ing with no backing
+// row — silent stale-hit corruption). An explicit `DELETE FROM observations
+// WHERE id = ?` fires obs_after_delete cleanly (sentinel removes the old terms),
+// then the plain INSERT fires obs_after_insert. This is the same delete-then-
+// insert pattern every other writer in the kit uses against this table.
+
+const DELETE_OBSERVATION_BY_ID_SQL = `DELETE FROM observations WHERE id = ?`;
+
 const INSERT_OBSERVATION_SQL = `
 INSERT INTO observations
   (id, tier, source_file, source_line, source_sha1, heading_path, body,
@@ -304,6 +338,16 @@ VALUES
    @write_source, @trust, @created_at, @superseded_by, @deleted_at)
 `;
 
+const INSERT_SCRATCHPAD_OBSERVATION_SQL = `
+INSERT INTO observations
+  (id, tier, source_file, source_line, source_sha1, heading_path, body,
+   write_source, trust, created_at, superseded_by, deleted_at)
+VALUES
+  (@id, @tier, @source_file, @source_line, @source_sha1, @heading_path, @body,
+   @write_source, @trust, @created_at, @superseded_by, @deleted_at)
+ON CONFLICT(id) DO NOTHING
+`;
+
 const UPSERT_FILE_SQL = `
 INSERT INTO files (path, mtime, sha1, indexed_at)
 VALUES (@path, @mtime, @sha1, @indexed_at)
@@ -322,10 +366,48 @@ const DELETE_OBSERVATIONS_FOR_PATH_SQL = `DELETE FROM observations WHERE source_
  */
 function replaceObservationsForFile(db, { source, observations, mtime, sha1, projectRoot, userDir, now }) {
   const source_file = relativeSource(source.path, { projectRoot, userDir });
+  // File-scoped delete clears THIS file's own rows so a re-index of a changed
+  // file is idempotent. It only matches rows whose source_file is this path, so
+  // a fact's row (source_file = context/memory/*.md) is untouched when the
+  // scratchpad (context/MEMORY.md) is re-indexed, and vice versa — the
+  // cross-file id collision is handled by the precedence-keyed insert below,
+  // NOT by this delete (Bug 1).
   db.prepare(DELETE_OBSERVATIONS_FOR_PATH_SQL).run(source_file);
-  const insert = db.prepare(INSERT_OBSERVATION_SQL);
-  for (const obs of observations) {
-    insert.run(obs);
+  // Archive-beats-scratchpad precedence (Bug 1): a fact row wins the id by
+  // explicitly deleting any existing row for that id first (firing the FTS
+  // 'delete' sentinel cleanly) then inserting; a scratchpad row yields via
+  // ON CONFLICT(id) DO NOTHING. Within a FULL pass (reindexFull, or a
+  // reindexBoot that re-walks both sources) this is order-independent — the
+  // fact row always wins (listObservationSources walks scratchpad-before-facts
+  // per tier, but either order lands the same surviving row).
+  //
+  // INCREMENTAL caveat (skill-review I1): on the mtime-skip boot path / the
+  // single-file watcher path, only the CHANGED source is re-processed. If a
+  // fact file is removed while its scratchpad twin (same id) is untouched, the
+  // orphan-prune drops the fact row and the skipped scratchpad's DO-NOTHING
+  // insert never re-fires — so the id momentarily vanishes from search until
+  // the scratchpad is next edited (which re-inserts it). `cmk forget` does NOT
+  // hit this: it tombstones the fact AND scrubs the scratchpad bullet in the
+  // same op (forget.mjs scrubAllScratchpads), so the only window is a manual
+  // hand-`rm` of a context/memory/*.md leaving the bullet behind — a rare,
+  // self-healing transition, documented + tested rather than resurrected.
+  //
+  // The DELETE-by-id is UNQUALIFIED (no tier/source_file filter) by design and
+  // safe: ids are content-addressed WITH the tier as a prefix (`P-`/`L-`/`U-`),
+  // so a P-tier and U-tier fact can never share an id — no cross-tier delete is
+  // possible. (Defended by the P/U-same-content tier test below.)
+  if (source.kind === 'fact') {
+    const deleteById = db.prepare(DELETE_OBSERVATION_BY_ID_SQL);
+    const insert = db.prepare(INSERT_OBSERVATION_SQL);
+    for (const obs of observations) {
+      deleteById.run(obs.id);
+      insert.run(obs);
+    }
+  } else {
+    const insert = db.prepare(INSERT_SCRATCHPAD_OBSERVATION_SQL);
+    for (const obs of observations) {
+      insert.run(obs);
+    }
   }
   db.prepare(UPSERT_FILE_SQL).run({
     path: source_file,
@@ -370,6 +452,9 @@ export function reindexBoot({ projectRoot, userDir, db, now }) {
       userDir,
       now: ts,
     });
+    // observationsAffected counts insert-ATTEMPTS, not net rows: a fact that
+    // displaces a same-id scratchpad row (Bug 1 precedence) is net-zero but
+    // counts as one here. It's a "work done" metric, not a row-count invariant.
     return result.observations.length;
   });
 
@@ -537,6 +622,9 @@ export function reindexFull({ projectRoot, userDir, db, now }) {
       userDir,
       now: ts,
     });
+    // observationsAffected counts insert-ATTEMPTS, not net rows: a fact that
+    // displaces a same-id scratchpad row (Bug 1 precedence) is net-zero but
+    // counts as one here. It's a "work done" metric, not a row-count invariant.
     return result.observations.length;
   });
 

package/src/inject-context.mjs

@@ -35,7 +35,7 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { SCRATCHPADS_BY_TIER, resolveTierRoot, ID_PATTERN } from './tier-paths.mjs';
 import { nowIso } from './audit-log.mjs';
-import { detectStaleness } from './lazy-compress.mjs';
+import { detectStaleness, isJournalStale } from './lazy-compress.mjs';
 import { isProvenanceCommentLine, parseBulletProvenance } from './provenance.mjs';
 import { listConflictQueue } from './conflict-queue.mjs';
 import { listReviewQueue } from './review-queue.mjs';
@@ -787,18 +787,28 @@ export function injectContext({
   let lazyTrigger = null;
   try {
     const verdict = detectStaleness({ projectRoot, now: ts });
-    lazyTrigger = { verdict: verdict.action, reason: verdict.reason };
-    if (
+    // Task 159 (D-169): journal-staleness is an INDEPENDENT spawn trigger — the
+    // detached lazy worker syncs DECISIONS.md unconditionally, so a session that's
+    // compress-fresh (or cron-active) but has new un-journaled decisions must
+    // still spawn, else the journal never renders without a clean SessionEnd
+    // (the Task-105/D-75 no-clean-exit class). Cron handles compress but NOT the
+    // journal, so cron-active + a stale journal SHOULD spawn (compress skips
+    // inside, the journal syncs). It is NOT a competing detectStaleness verdict
+    // (one verdict → one compress dispatch; folding journal in would suppress
+    // compress work — the separately-correct-jointly-broken class).
+    const journalStale = isJournalStale(projectRoot);
+    lazyTrigger = { verdict: verdict.action, reason: verdict.reason, journalStale };
+    const compressStale =
       verdict.action === 'stale-now' ||
       verdict.action === 'stale-daily' ||
-      verdict.action === 'stale-weekly'
-    ) {
+      verdict.action === 'stale-weekly';
+    if (compressStale || journalStale) {
       const spawner = typeof testSpawnLazy === 'function' ? testSpawnLazy : spawnLazyCompress;
       const spawnResult = spawner(projectRoot, compressLazyPath);
       lazyTrigger = { ...lazyTrigger, ...spawnResult };
     }
   } catch (err) {
-    // detectStaleness should be defensive; if it throws, log + continue.
+    // detectStaleness / isJournalStale should be defensive; if they throw, log + continue.
     lazyTrigger = { verdict: 'error', error: err?.message ?? String(err) };
   }