@lh8ppl/claude-memory-kit 0.3.2 → 0.3.3

package/README.md

@@ -47,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
 
@@ -62,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.2",
+  "version": "0.3.3",
   "description": "cmk — the CLI for claude-memory-kit. Per-project, in-repo memory system for Claude Code.",
   "type": "module",
   "bin": {

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/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) };
   }
 

package/src/lazy-compress.mjs

@@ -44,6 +44,7 @@ import {
 import { dailyDistill } from './daily-distill.mjs';
 import { weeklyCurate } from './weekly-curate.mjs';
 import { compressSession } from './compress-session.mjs';
+import { syncDecisionsJournal } from './decisions-journal.mjs';
 
 const DEFAULT_DAILY_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const DEFAULT_WEEKLY_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
@@ -132,6 +133,61 @@ function recentMdMtimeMs(projectRoot) {
   }
 }
 
+const MEMORY_REL = ['context', 'memory'];
+const DECISIONS_MD_REL = ['context', 'DECISIONS.md'];
+
+/**
+ * Task 159 (D-169): is the decision journal behind the captured decision facts?
+ *
+ * INDEPENDENT of compress staleness — a compress-fresh session can still have
+ * new `type:project` decision facts that aren't yet rendered into DECISIONS.md.
+ * So this is its OWN boolean (NOT a competing detectStaleness verdict, which can
+ * only return ONE action and would suppress compress work). Used as an ADDITIONAL
+ * spawn condition in inject-context, and the journal is synced unconditionally
+ * inside runLazyCompress.
+ *
+ * **O(1) — runs inline on EVERY SessionStart, so it must compose with the 500ms
+ * NFR-1 budget.** It uses `context/memory/INDEX.md` as the freshness proxy:
+ * `write-fact.mjs` rewrites INDEX.md on every fact write, so `INDEX.md` mtime ≥
+ * the newest fact file always (verified). Comparing two file mtimes is O(1) — vs
+ * stat-every-fact, which was ~130ms on a 307-fact corpus and grew linearly (a
+ * self-review find; that approach would blow the budget on a large repo).
+ *
+ * Stale ⇔ a `project_*.md` fact exists (short-circuit on the first one — no stat)
+ * AND (DECISIONS.md is missing OR older than INDEX.md). Trade-off: INDEX.md
+ * covers ALL fact types, so a feedback-only write can flag the journal stale →
+ * one spurious detached sync (~175ms, idempotent, never a correctness issue) —
+ * acceptable for an O(1) check on the hot SessionStart path. Defensive: any
+ * throw → false (never block SessionStart on a stat error).
+ *
+ * @param {string} projectRoot
+ * @returns {boolean}
+ */
+export function isJournalStale(projectRoot) {
+  if (!projectRoot) return false;
+  try {
+    const memDir = join(projectRoot, ...MEMORY_REL);
+    if (!existsSync(memDir)) return false;
+    // Any project (decision) fact at all? Short-circuit on the first — no stat,
+    // just the dirent name. No project facts → nothing to journal → not stale.
+    const hasDecisionFact = readdirSync(memDir).some(
+      (name) => name.startsWith('project_') && name.endsWith('.md'),
+    );
+    if (!hasDecisionFact) return false;
+    const journalPath = join(projectRoot, ...DECISIONS_MD_REL);
+    if (!existsSync(journalPath)) return true; // facts exist, journal missing → stale
+    // INDEX.md is the O(1) freshness proxy (rewritten on every fact write). If
+    // it's absent (pre-index repo), fall back to "facts exist + journal exists"
+    // → treat as fresh (a reindex will create INDEX.md; the session-end sync
+    // covers the journal regardless).
+    const indexPath = join(memDir, 'INDEX.md');
+    if (!existsSync(indexPath)) return false;
+    return statSync(indexPath).mtimeMs > statSync(journalPath).mtimeMs;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Cheap inline staleness check. Runs in <5ms — one stat + a few existsSync.
  *
@@ -254,6 +310,31 @@ export async function runLazyCompress({
     });
   }
 
+  // Task 159 (D-169): sync the decision journal UNCONDITIONALLY, before any
+  // compress gate. This is the SessionStart fallback path for sessions that never
+  // cleanly closed (Claude Code fires SessionEnd only on clean window-close — the
+  // Task-105/D-75 class), where the primary session-end sync never ran. It must
+  // run regardless of the compress verdict (cooldown / cron-active / fresh) — a
+  // cron-active or compress-fresh session can still have new decisions. Cheap pure
+  // file I/O (~175ms), idempotent (a no-change run rewrites nothing), best-effort
+  // (syncDecisionsJournal has its own try/catch + soft-error return). It does NOT
+  // touch the Haiku cooldown — that gate is for the LLM compress passes only.
+  // Door 4: log the outcome to lazy-compress.log so a silent fallback-path
+  // failure (e.g. a DECISIONS.md permissions error) leaves a trace — the rest of
+  // this function is fully NDJSON-observable, and the journal sync must be too.
+  const journalResult = syncDecisionsJournal({ projectRoot, now: ts });
+  writeLazyLogEntry({
+    projectRoot,
+    entry: {
+      ts,
+      scope: 'journal-sync',
+      action: journalResult?.error ? 'error' : journalResult?.written ? 'written' : 'no-change',
+      written: journalResult?.written ?? false,
+      appended: journalResult?.appended ?? 0,
+      ...(journalResult?.error ? { error: journalResult.error } : {}),
+    },
+  });
+
   // Cooldown gate up front — composes with shared 120s marker.
   if (isCooldownActive({ projectRoot, now: ts, cooldownMs })) {
     const duration_ms = Date.now() - t0;

package/src/mcp-server.mjs

@@ -155,6 +155,7 @@ function makeMkSearch({ db, semanticBackend, projectRoot }) {
       db, query,
       mode: wantMode,
       scope,
+      projectRoot, // Task 156: the decisions scope reads context/DECISIONS.md
       tier,
       since,
       limit,
@@ -181,6 +182,13 @@ function makeMkSearch({ db, semanticBackend, projectRoot }) {
 function makeMkGet({ db }) {
   // Thin adapter over the shared read core (read-core.getObservations) — the
   // SAME logic the CLI `cmk get` calls (ADR-0014 parity).
+  //
+  // D-163 (BINDING): mk_get is tombstone-BLIND and must stay that way. It calls
+  // getObservations WITHOUT `includeTombstoned`, so a forgotten fact returns
+  // `not found`. Tombstone recovery is a HUMAN-only verb (`cmk get
+  // --include-tombstoned`); the agent must NEVER recover a fact the user
+  // forgot (resurfacing a deleted fact is the worst memory-product failure).
+  // Do NOT add an includeTombstoned param to this tool.
   return async ({ ids }) => ({
     content: [{ type: 'text', text: JSON.stringify(getObservations(db, ids), null, 2) }],
   });
@@ -563,7 +571,7 @@ export function buildMcpServer({ projectRoot, userDir, db, semanticBackend }) {
       inputSchema: {
         query: z.string().min(1).describe('search query'),
         mode: z.enum(['keyword', 'semantic', 'hybrid']).optional(),
-        scope: z.enum(['facts', 'transcripts']).optional().describe("'facts' (default) = curated memory; 'transcripts' = the raw session record — the LAST-RESORT recall tier, search it only when curated memory has no answer"),
+        scope: z.enum(['facts', 'transcripts', 'decisions']).optional().describe("'facts' (default) = curated memory; 'transcripts' = the raw session record (LAST-RESORT — only when curated memory has no answer); 'decisions' = the append-only decision journal (context/DECISIONS.md) — use for decision-HISTORY / evolution / 'what did we reject / why did X change' queries (it returns superseded + retracted entries the live fact store no longer carries)"),
         tier: z.enum(['U', 'P', 'L']).optional(),
         since: z.string().optional().describe('ISO 8601 timestamp'),
         limit: z.number().int().positive().max(1000).optional(),

package/src/read-core.mjs

@@ -6,7 +6,10 @@
 // surfaces, one implementation. Pure (db + args in, plain data out); the MCP
 // adapter wraps the result in a content envelope, the CLI adapter prints it.
 
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { ID_PATTERN } from './tier-paths.mjs';
+import { parse as parseFrontmatter } from './frontmatter.mjs';
 
 const GET_COLUMNS =
   'id, body, heading_path, source_file, source_line, tier, trust, ' +
@@ -15,17 +18,76 @@ const GET_COLUMNS =
 /**
  * Fetch full observation rows by id. An invalid-format or missing id becomes
  * a `{ id, error }` entry (the array stays positionally aligned with `ids`).
+ *
+ * Task 155 (D-163) — opt-in tombstone recovery. By DEFAULT this is live-only:
+ * a forgotten id (its index row pruned by Task 110, the body moved to
+ * `context/memory/archive/tombstones/<id>.md`) returns `not found`. The
+ * automatic recall surfaces (the SessionStart snapshot, `mk_search`, `mk_get`)
+ * MUST stay on this default — a deleted fact must remain invisible to the agent
+ * (resurfacing it is the worst memory-product failure). ONLY an explicit
+ * HUMAN-driven `cmk get --include-tombstoned` opts in, passing
+ * `{ includeTombstoned: true, projectRoot }`; on a live miss it then reads the
+ * tombstone file directly and returns its body marked `tombstoned: true`.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.includeTombstoned=false] human-only recovery opt-in
+ * @param {string}  [opts.projectRoot] required when includeTombstoned (to find the archive)
  */
-export function getObservations(db, ids) {
+export function getObservations(db, ids, { includeTombstoned = false, projectRoot } = {}) {
   const stmt = db.prepare(`SELECT ${GET_COLUMNS} FROM observations WHERE id = ?`);
   return ids.map((id) => {
     if (!ID_PATTERN.test(id)) return { id, error: 'invalid id format' };
     const row = stmt.get(id);
-    if (!row) return { id, error: 'not found' };
-    return row;
+    if (row) return row; // a LIVE hit always wins — recovery is a miss-only fallback
+    // Live miss. Recovery is opt-in AND needs projectRoot to locate the archive.
+    if (includeTombstoned && projectRoot) {
+      const recovered = readTombstone(projectRoot, id);
+      if (recovered) return recovered;
+    }
+    return { id, error: 'not found' };
   });
 }
 
+/**
+ * Read a tombstoned fact's body + deletion provenance from
+ * `<projectRoot>/context/memory/archive/tombstones/<id>.md`. Returns a row-like
+ * object marked `tombstoned: true`, or null if no tombstone exists for the id.
+ * Read-only; never un-tombstones (that would be a separate `restore` verb).
+ */
+function readTombstone(projectRoot, id) {
+  // SAFETY: `id` is interpolated into the path, but every caller reaches here
+  // ONLY after getObservations' `ID_PATTERN.test(id)` gate (anchored
+  // /^[PUL]-[base32]{8}$/ — no `.`/`/`/`\`), so it cannot path-traverse out of
+  // the tombstones dir. Do NOT call readTombstone before that validation.
+  const tombPath = join(
+    projectRoot, 'context', 'memory', 'archive', 'tombstones', `${id}.md`,
+  );
+  if (!existsSync(tombPath)) return null;
+  const { frontmatter, body } = parseFrontmatter(readFileSync(tombPath, 'utf8'));
+  const fm = frontmatter ?? {};
+  // `tombstoned: true` is the SOLE discriminator for recovered-vs-live — a live
+  // row never carries it. Consumers must key off this, NOT off `deleted_at`
+  // presence (a live row can carry a null deleted_at too). A malformed/garbled
+  // tombstone still returns its raw body + null provenance (graceful degrade —
+  // a human recovering is precisely the case where something went wrong).
+  return {
+    id,
+    body: body ?? '',
+    heading_path: fm.title ?? null,
+    source_file: `context/memory/archive/tombstones/${id}.md`,
+    source_line: 1, // synthetic — the tombstone file has no meaningful source line
+    tier: fm.tier ?? null,
+    trust: fm.trust ?? null,
+    write_source: fm.write_source ?? null,
+    created_at: fm.created_at ?? fm.at ?? null,
+    superseded_by: fm.superseded_by ?? null,
+    deleted_at: fm.deleted_at ?? null,
+    deleted_reason: fm.deleted_reason ?? null,
+    deleted_by: fm.deleted_by ?? null,
+    tombstoned: true,
+  };
+}
+
 /** The canonical Markdown citation link for an id. Pure (no DB). */
 export function citeLink(id) {
   if (!ID_PATTERN.test(id)) return { ok: false, error: 'id must match ID_PATTERN' };

package/src/remember-core.mjs

@@ -18,7 +18,7 @@
 
 import { resolve as resolvePath } from 'node:path';
 import { hashContent } from './content-hash.mjs';
-import { sanitizePrivacyTags } from './privacy.mjs';
+import { sanitizeForTitle } from './sanitize.mjs';
 import { writeFact as defaultWriteFact } from './write-fact.mjs';
 import { buildRichFactBody, slugifyFact } from './rich-fact.mjs';
 
@@ -54,16 +54,15 @@ export function rememberRich(text, options = {}, deps = {}) {
   const projectRoot = deps.projectRoot ?? resolvePath(process.cwd());
   const write = deps.writeFact ?? defaultWriteFact;
 
-  // Strip <private>…</private> BEFORE deriving/slicing the title (cut-gate
-  // v0.3.1 clean-build finding). writeFact also strips, but it receives a title
-  // already sliced to 80 chars — and an 80-char cut that lands inside a private
-  // span SEVERS the closing tag, so writeFact's `<private>…</private>` regex no
-  // longer matches and the secret survives in the frontmatter title + INDEX.md.
-  // Stripping the intact text here means the slice only ever sees redacted text.
-  const headline = sanitizePrivacyTags(String(text).trim());
-  const safeTitle = options.title
-    ? sanitizePrivacyTags(String(options.title).trim())
-    : '';
+  // Sanitize BEFORE deriving/slicing the title — the slug is `slugifyFact(title)`,
+  // so anything still in the title here lands in the committed FILENAME + INDEX,
+  // which writeFact's later body/title sanitization can't undo. sanitizeForTitle
+  // (the ONE shared helper — sanitize.mjs) strips <private> + abstracts home
+  // paths, the two cut-gate findings (v0.3.1 + F-V0.3.3-2). The body itself keeps
+  // its <private> redaction via the headline below; home paths in the body are
+  // abstracted by writeFact downstream.
+  const headline = sanitizeForTitle(text);
+  const safeTitle = options.title ? sanitizeForTitle(options.title) : '';
   const title = safeTitle || headline.split('\n')[0].slice(0, 80);
   const body = buildRichFactBody({ text: headline, why: options.why, how: options.how });
   // `links` arrives as an ARRAY from the MCP tool (z.array) and as a
@@ -97,10 +96,11 @@ export function rememberRich(text, options = {}, deps = {}) {
 
 /** The title rememberRich() will derive for `text`/`options` (for caller messages). */
 export function richFactTitle(text, options = {}) {
-  // Mirror rememberRich: strip <private> before slicing so the preview a caller
-  // echoes to the console never carries private content either (cut-gate v0.3.1).
-  const safeTitle = options.title ? sanitizePrivacyTags(String(options.title).trim()) : '';
-  return safeTitle || sanitizePrivacyTags(String(text).trim()).split('\n')[0].slice(0, 80);
+  // Mirror rememberRich EXACTLY (the SAME sanitizeForTitle helper) so the preview
+  // a caller echoes never carries <private> content or the username, and stays
+  // identical to the title rememberRich actually derives + stores.
+  const safeTitle = options.title ? sanitizeForTitle(options.title) : '';
+  return safeTitle || sanitizeForTitle(text).split('\n')[0].slice(0, 80);
 }
 
 /**

package/src/sanitize.mjs

@@ -13,6 +13,8 @@
 // (local, gitignored) — machine-specific absolute paths are the whole point
 // of the local tier, so they stay verbatim there.
 
+import { sanitizePrivacyTags } from './privacy.mjs';
+
 // Each pattern matches an absolute home-directory prefix up to (but not
 // including) the next path separator / whitespace / quote, so the remainder
 // of the path is preserved. Username char class excludes separators, spaces,
@@ -37,3 +39,31 @@ export function sanitizeHomePaths(text) {
   for (const re of HOME_PATH_PATTERNS) out = out.replace(re, '~');
   return out;
 }
+
+/**
+ * Sanitize a string that is about to become a fact TITLE — and therefore the
+ * fact's SLUG (`slugifyFact(title)`) and committed FILENAME + INDEX.md link.
+ *
+ * THE INVARIANT (F-V0.3.3-2, cut-blocker): a slug is derived from the title
+ * BEFORE `writeFact` runs, and `writeFact` only sanitizes the body + the
+ * frontmatter `title:` field — NOT the slug/filename. So anything still in the
+ * title at slug-derivation time leaks into the COMMITTED FILENAME, which no
+ * downstream sanitization can undo. Every caller that derives a slug from
+ * user/Haiku text MUST route the title through THIS helper first, so the leak
+ * class is closed in ONE place instead of being re-missed per call site
+ * (cmk remember had it; auto-extract had the same bug — the comment there even
+ * wrongly claimed "writeFact already sanitizes").
+ *
+ * Two transforms, both required, privacy-first:
+ *   - sanitizePrivacyTags: strip `<private>…</private>` (v0.3.1 — a later
+ *     80-char title slice that severs the closing tag defeats writeFact's regex).
+ *   - sanitizeHomePaths: `C:\Users\<you>` → `~` (F-V0.3.3-2 — the username leak).
+ * Privacy-first is the safe order: the private span (which may itself contain a
+ * home path) is removed wholesale before homepath-sanitize ever sees a fragment.
+ *
+ * @param {string} s
+ * @returns {string} the redacted + abstracted, trimmed string (safe to slug)
+ */
+export function sanitizeForTitle(s) {
+  return sanitizeHomePaths(sanitizePrivacyTags(String(s).trim()));
+}

package/src/search.mjs

@@ -42,6 +42,8 @@
 // hybrid + semantic paths. Production callers (the `cmk search` CLI in
 // subcommands.mjs) pass undefined; v0.1.x lands the real backend.
 
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { ERROR_CATEGORIES, errorResult } from './result-shapes.mjs';
 import { VALID_TIERS } from './tier-paths.mjs';
 
@@ -58,9 +60,16 @@ const MAX_LIMIT = 1000;
 // index (L1, the default). 'transcripts' = the SEPARATE raw-transcript
 // chunk index (the L3 last-resort tier) — reached ONLY when explicitly
 // asked, so raw history never pollutes curated results.
+// Task 156 (D-168) — 'decisions' = the append-only decision journal
+// (context/DECISIONS.md). Deliberately NOT FTS-indexed (a derived view,
+// skipped like INDEX.md), so this scope scans the markdown file directly. It
+// is the recall path for decision-HISTORY / "what did we reject / why did X
+// change" queries — the journal carries the retract/supersede trail the flat
+// fact store no longer holds. Keyword-only (the journal is not embedded).
 export const SEARCH_SCOPES = Object.freeze({
   FACTS: 'facts',
   TRANSCRIPTS: 'transcripts',
+  DECISIONS: 'decisions',
 });
 
 const TRUST_ORDINAL = Object.freeze({
@@ -117,8 +126,12 @@ function validateInput(opts) {
     }
   }
   const scope = opts.scope ?? SEARCH_SCOPES.FACTS;
-  if (scope !== SEARCH_SCOPES.FACTS && scope !== SEARCH_SCOPES.TRANSCRIPTS) {
-    errors.push(`scope: must be one of facts/transcripts (got ${JSON.stringify(scope)})`);
+  if (
+    scope !== SEARCH_SCOPES.FACTS &&
+    scope !== SEARCH_SCOPES.TRANSCRIPTS &&
+    scope !== SEARCH_SCOPES.DECISIONS
+  ) {
+    errors.push(`scope: must be one of facts/transcripts/decisions (got ${JSON.stringify(scope)})`);
   }
   if (scope === SEARCH_SCOPES.TRANSCRIPTS) {
     // Chunks carry no tier/trust/created_at — rejecting these is more honest
@@ -133,6 +146,26 @@ function validateInput(opts) {
       }
     }
   }
+  if (scope === SEARCH_SCOPES.DECISIONS) {
+    // The journal is a flat markdown file, not the index: it carries no
+    // tier/trust/created_at columns and isn't embedded. Reject those filters +
+    // semantic/hybrid modes (same explicit-vs-configured honesty as transcripts).
+    for (const [key, label] of [
+      ['tier', 'tier'],
+      ['minTrust', 'minTrust'],
+      ['since', 'since'],
+    ]) {
+      if (opts[key] !== undefined) {
+        errors.push(`${label}: not supported under the decisions scope (journal entries carry no ${label})`);
+      }
+    }
+    if (mode !== SEARCH_MODES.KEYWORD) {
+      errors.push(`mode: only keyword is supported under the decisions scope (the journal is not embedded)`);
+    }
+    if (typeof opts.projectRoot !== 'string' || opts.projectRoot.length === 0) {
+      errors.push('projectRoot: required for the decisions scope (to locate context/DECISIONS.md)');
+    }
+  }
   return { errors, mode, scope };
 }
 
@@ -394,6 +427,87 @@ function flattenSnippet(s) {
   return flat.length > TRANSCRIPT_SNIPPET_MAX ? flat.slice(0, TRANSCRIPT_SNIPPET_MAX) + '…' : flat;
 }
 
+// --- Decisions-scope keyword backend (Task 156, the decision journal) ---
+
+// The journal entry shape (decisions-journal.mjs buildDecisionEntry):
+//   <!-- decision:P-XXXXXXXX -->
+//   ### <title>                       (a retracted entry carries _(retracted DATE)_)
+//   **When:** <date> · **Fact:** `<id>`
+//   **Why:** <why>                    (optional)
+// Entries are separated by the machine marker; we split on it, match the query
+// as a case-insensitive substring over the entry text, and report the retract
+// marker so recall can answer "did this change / what did we reject".
+const DECISION_MARKER_RE = /<!--\s*decision:([PUL]-[^\s]+)\s*-->/g;
+const DECISIONS_SNIPPET_MAX = 240;
+
+function runDecisionsKeywordSearch(_db, opts) {
+  const file = join(opts.projectRoot, 'context', 'DECISIONS.md');
+  if (!existsSync(file)) return []; // no journal yet → empty, not an error
+  const content = readFileSync(file, 'utf8');
+
+  // Split the body into entry spans keyed by the decision marker. Each span runs
+  // from its marker to the next marker (or EOF). A marker is an entry boundary
+  // ONLY at line-start — the writer (buildDecisionEntry) always emits it first
+  // on its own line, so a marker QUOTED inside a Why/body (a meta-decision about
+  // the journal format, or a fact citing another's marker) does NOT false-split
+  // the entry (skill-review I2). DECISION_MARKER_RE is module-level /g + reset
+  // here; the function is fully synchronous (no await between reset and the
+  // loop), so there is no shared-state re-entrancy hazard.
+  const markers = [];
+  let m;
+  DECISION_MARKER_RE.lastIndex = 0;
+  while ((m = DECISION_MARKER_RE.exec(content)) !== null) {
+    const atLineStart = m.index === 0 || content[m.index - 1] === '\n';
+    if (atLineStart) markers.push({ id: m[1], start: m.index });
+  }
+
+  const needle = opts.query.trim().toLowerCase();
+  const hits = [];
+  for (let i = 0; i < markers.length; i++) {
+    const start = markers[i].start;
+    const end = i + 1 < markers.length ? markers[i + 1].start : content.length;
+    const block = content.slice(start, end);
+    // Strip the plumbing (the `<!-- decision:ID -->` marker + the `### ` heading
+    // hashes) BEFORE matching, so the query matches the human signal (title /
+    // When / Why) — NOT the literal word "decision" inside every marker comment
+    // (the self-review false-positive: searching "decision" matched all entries
+    // via their markers). Uses a FRESH regex (not the shared module-level
+    // DECISION_MARKER_RE) so the loop's .exec lastIndex isn't clobbered.
+    const cleaned = block
+      .replace(/<!--\s*decision:[PUL]-[^\s]+\s*-->/g, '')
+      .replace(/^#{1,6}\s+/gm, '');
+    if (!cleaned.toLowerCase().includes(needle)) continue;
+
+    // The line offset of the marker = source_line drill-back into DECISIONS.md.
+    const sourceLine = content.slice(0, start).split('\n').length;
+    // Retracted-tag detection mirrors the WRITER's contract: the tag sits on its
+    // own line DIRECTLY after the `### ` heading (decisions-journal.mjs §2), so
+    // scope the check there — NOT a raw-block substring, which would mislabel an
+    // active entry whose Why merely MENTIONS "_(retracted" (skill-review I1).
+    const headingIdx = block.indexOf('### ');
+    const afterHeading =
+      headingIdx === -1 ? '' : block.slice(block.indexOf('\n', headingIdx) + 1);
+    const retracted = afterHeading.startsWith('_(retracted');
+    hits.push({
+      id: markers[i].id,
+      snippet: flattenSnippet(cleaned).slice(0, DECISIONS_SNIPPET_MAX),
+      source_file: 'context/DECISIONS.md',
+      source_line: sourceLine,
+      retracted,
+      // `score` is POSITIONAL (the marker index), NOT an FTS relevance rank —
+      // the journal is chronological, so a lower score = an earlier decision.
+      // Don't fuse/sort this against the facts/transcripts scopes' rank scores.
+      score: i,
+    });
+    // NB: `limit` is a CHRONOLOGICAL head, not a relevance top-N — it returns
+    // the first N matches in journal (oldest→newest) order, so a strongly
+    // relevant decision far down a long journal can be cut. Acceptable: the
+    // journal is bounded and chronological by design (M1, deliberate).
+    if (hits.length >= (opts.limit ?? DEFAULT_LIMIT)) break;
+  }
+  return hits;
+}
+
 // --- Reciprocal-rank fusion (hybrid mode) -----------------------------
 
 /**
@@ -445,8 +559,9 @@ export function search(opts = {}) {
   // Scope dispatch (Task 104.2): the transcripts scope swaps the keyword
   // backend; semantic/hybrid use the caller-prepared backend exactly like
   // the facts scope (prepareSemanticBackend({scope}) embeds the right table).
-  const keywordBackend =
-    scope === SEARCH_SCOPES.TRANSCRIPTS ? runTranscriptKeywordSearch : runKeywordSearch;
+  let keywordBackend = runKeywordSearch;
+  if (scope === SEARCH_SCOPES.TRANSCRIPTS) keywordBackend = runTranscriptKeywordSearch;
+  else if (scope === SEARCH_SCOPES.DECISIONS) keywordBackend = runDecisionsKeywordSearch;
 
   // Semantic + hybrid require an injected backend. Production v0.1.0
   // passes undefined → error with the not-yet-shipped hint. A future

package/src/session-end-tasks.mjs

@@ -35,6 +35,7 @@
 import { compressSession } from './compress-session.mjs';
 import { autoPersona } from './auto-persona.mjs';
 import { graduateAllScratchpads } from './graduate-session.mjs';
+import { syncDecisionsJournal } from './decisions-journal.mjs';
 
 /**
  * Run the two independent SessionEnd Haiku passes concurrently.
@@ -45,7 +46,7 @@ import { graduateAllScratchpads } from './graduate-session.mjs';
  * @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}>}
+ * @returns {Promise<{compressOutcome: PromiseSettledResult, personaOutcome: PromiseSettledResult, graduationOutcome: PromiseSettledResult, journalOutcome: PromiseSettledResult}>}
  */
 export async function runSessionEndTasks({ projectRoot, userDir, makeBackend, now }) {
   const [compressOutcome, personaOutcome] = await Promise.allSettled([
@@ -75,7 +76,30 @@ export async function runSessionEndTasks({ projectRoot, userDir, makeBackend, no
     graduationOutcome = { status: 'rejected', reason: err };
   }
 
-  return { compressOutcome, personaOutcome, graduationOutcome };
+  // Task 159 (D-169): auto-sync the decision journal. This is what makes
+  // DECISIONS.md "automatic" (D-164) — Task 147 BUILT the append logic but wired
+  // it to ONLY the manual `cmk digest`, so the journal never populated on its own.
+  // Same shape as the graduation sweep: SEQUENTIAL, pure local file I/O (reads the
+  // type:project fact files auto-extract wrote per-turn → rewrites DECISIONS.md),
+  // no Haiku/network (~175ms), no hook-ceiling risk, wrapped so a throw can't reject
+  // the hook. DISJOINT from compress (sessions/ tree) + persona (user-tier) +
+  // graduation (persona scratchpads) — nothing else in the block touches DECISIONS.md,
+  // so no lock contention. Session-end is the natural "this session's decisions
+  // landed → render them" boundary (squad's session-end Scribe instinct, made
+  // deterministic — the kit's typed-fact substrate needs no LLM to merge).
+  // syncDecisionsJournal is already best-effort (its own try/catch returns
+  // {written:false,error}); the wrapper here guards the unexpected synchronous throw.
+  let journalOutcome;
+  try {
+    journalOutcome = {
+      status: 'fulfilled',
+      value: syncDecisionsJournal({ projectRoot, now }),
+    };
+  } catch (err) {
+    journalOutcome = { status: 'rejected', reason: err };
+  }
+
+  return { compressOutcome, personaOutcome, graduationOutcome, journalOutcome };
 }
 
 /**
@@ -86,7 +110,7 @@ export async function runSessionEndTasks({ projectRoot, userDir, makeBackend, no
  * @param {{compressOutcome: PromiseSettledResult, personaOutcome: PromiseSettledResult}} outcomes
  * @returns {string[]}
  */
-export function summarizeSessionEnd({ compressOutcome, personaOutcome, graduationOutcome }) {
+export function summarizeSessionEnd({ compressOutcome, personaOutcome, graduationOutcome, journalOutcome }) {
   const lines = [];
 
   if (compressOutcome.status === 'fulfilled') {
@@ -123,5 +147,18 @@ export function summarizeSessionEnd({ compressOutcome, personaOutcome, graduatio
     }
   }
 
+  // journalOutcome is optional (Task 159) — pre-159 callers render no journal line.
+  if (journalOutcome) {
+    if (journalOutcome.status === 'fulfilled') {
+      const j = journalOutcome.value ?? {};
+      lines.push(
+        `cmk-compress-session: journal (written: ${j.written ?? false}, appended: ${j.appended ?? 0})\n`,
+      );
+    } else {
+      const e = journalOutcome.reason;
+      lines.push(`cmk-compress-session: journal sync failed: ${e?.message ?? e}\n`);
+    }
+  }
+
   return lines;
 }

package/src/subcommands.mjs

@@ -416,7 +416,19 @@ async function runSearch(queryParts, options) {
     let mode = explicitMode ?? resolveDefaultSearchMode({ projectRoot });
     // Task 104.2 — the L3 raw tier: `--scope transcripts` searches the
     // separate transcript-chunk index (synthetic T: ids; no tier/trust).
+    // Task 156 — `--scope decisions` scans context/DECISIONS.md (the decision
+    // journal) for decision-history / "what did we reject" recall.
     const scope = options?.scope ?? 'facts';
+    // Task 156 / v0.3.3 cut-gate-16: the `decisions` scope is keyword-only BY
+    // DESIGN — it scans the flat `context/DECISIONS.md` journal, which is NOT
+    // embedded (no vec table). So it can never go through the semantic backend.
+    // Coerce to keyword BEFORE the semantic block, silently — a user who has the
+    // hybrid default (from `--with-semantic`) must not see a scary
+    // "unknown-scope:decisions" warning (configured default) or hard exit-2
+    // (explicit --mode) for using a real, shipped scope. The recall just works.
+    if (scope === 'decisions') {
+      mode = SEARCH_MODES.KEYWORD;
+    }
     let semanticBackend;
     if (mode === SEARCH_MODES.SEMANTIC || mode === SEARCH_MODES.HYBRID) {
       const { prepareSemanticBackend } = await import('./semantic-backend.mjs');
@@ -443,6 +455,7 @@ async function runSearch(queryParts, options) {
       query,
       mode,
       scope,
+      projectRoot, // Task 156: the decisions scope reads context/DECISIONS.md
       minTrust: options?.minTrust,
       tier: options?.tier,
       since: options?.since,
@@ -464,9 +477,15 @@ async function runSearch(queryParts, options) {
     for (const hit of r.results) {
       // Plain-text output suitable for terminal piping. Snippet uses
       // FTS5's <b>...</b> markers; preserved as-is so callers can pipe
-      // to a TUI that renders them OR strip via sed. Transcript hits carry
-      // no tier/trust (raw chunks) — the column shows the scope instead.
-      const provenance = hit.tier ? `${hit.tier}/${hit.trust}` : 'transcript';
+      // to a TUI that renders them OR strip via sed. Hits with no tier/trust
+      // (raw transcript chunks; decision-journal entries) show the scope's
+      // label instead — 'transcript' for the L3 raw tier, 'decision' for the
+      // journal (Task 156), plus a `(retracted)` marker so the "what did we
+      // reject" trail is visible at a glance.
+      let provenance;
+      if (hit.tier) provenance = `${hit.tier}/${hit.trust}`;
+      else if (r.scope === 'decisions') provenance = hit.retracted ? 'decision (retracted)' : 'decision';
+      else provenance = 'transcript';
       console.log(
         `${hit.id}\t${provenance}\t${hit.source_file}:${hit.source_line}\t${hit.snippet}`,
       );
@@ -512,10 +531,19 @@ export function withReadDb(fn, deps = {}) {
   }
 }
 
-export function runGet(ids, _options = {}, _command, deps = {}) {
+export function runGet(ids, options = {}, _command, deps = {}) {
   const log = deps.log ?? console.log;
   const list = Array.isArray(ids) ? ids : [ids];
-  const rows = withReadDb((db) => getObservations(db, list), deps);
+  // Task 155 (D-163): `--include-tombstoned` is the HUMAN-only recovery opt-in.
+  // It's a CLI flag ONLY — the MCP mk_get tool never exposes it, so automatic
+  // recall stays tombstone-blind. projectRoot is resolved the same way
+  // withReadDb does, so the tombstone-file fallback can find the archive.
+  const includeTombstoned = options.includeTombstoned === true;
+  const projectRoot = deps.projectRoot ?? resolvePath(process.cwd());
+  const rows = withReadDb(
+    (db) => getObservations(db, list, { includeTombstoned, projectRoot }),
+    deps,
+  );
   log(JSON.stringify(rows, null, 2));
   // All-missing/invalid → exit 2 (lets a script tell "nothing matched" from a hit).
   if (rows.length > 0 && rows.every((r) => r.error)) process.exitCode = 2;
@@ -1999,6 +2027,12 @@ export const subcommands = [
     description: 'fetch full observation bodies + provenance by ID (parity with the mk_get MCP tool)',
     milestone: 108,
     argSpec: [{ flags: '<ids...>', description: 'one or more citation IDs (e.g. P-S79MJHFN)' }],
+    optionSpec: [
+      {
+        flags: '--include-tombstoned',
+        description: 'also recover forgotten (tombstoned) facts from the archive — human-only; the AI never reads tombstones',
+      },
+    ],
     action: runGet,
   },
   {

package/template/.claude/skills/memory-search/SKILL.md

@@ -63,6 +63,26 @@ Hits are raw turn excerpts (dialogue + the tools the agent ran), keyed
 whole turns. If something found here is durably useful, say so in the
 summary so the caller can capture it as a proper fact.
 
+## Decision HISTORY — the `decisions` scope
+
+For "what did we DECIDE about X" a normal fact search (steps 1-3) is enough —
+the decision fact carries its own **Why**. But when the question is about how a
+decision **evolved**, what we **reject**ed or moved away from, or **why X
+changed** ("did we ever consider Y?", "weren't we using Postgres?", "what did
+we decide and did it change?"), search the **decision journal** — the
+append-only `context/DECISIONS.md`, which keeps superseded + retracted entries
+the live fact store no longer carries:
+
+- MCP: `mk_search` with `scope: "decisions"`.
+- CLI: `cmk search "<topic>" --scope decisions`
+
+Hits are decision entries keyed by their fact id, labelled `decision` (or
+`decision (retracted)` for a reversed one). The retracted/superseded entries
+ARE the answer to "what did we reject" — surface them explicitly, with the
+date, so the caller sees the trail. Use this scope IN ADDITION to the fact
+ladder when the question has a history/evolution axis; the fact search answers
+the "current decision", the journal answers "how it got there".
+
 ## When the query is vague
 
 If you cannot form a concrete query, look at recent activity first, then

package/template/CLAUDE.md.template

@@ -29,6 +29,7 @@ The `cmk doctor` health checks verify each layer is wired correctly: install int
 The snapshot injected at session start is a **bounded hot index, not everything** — there is a deeper, queryable archive. When a question is "what did we decide / what's our X / how does the user work / what's the setup / **how is this project structured or built / where does X live / what's the architecture**," **query your memory instead of re-deriving the answer from scratch** — the structure is a recorded decision, recall it before re-reading the files to reconstruct it:
 
 - **`cmk search "<topic>"`** — find any captured fact (decisions, preferences, config, lessons) across the project + user tiers.
+- **`cmk search "<topic>" --scope decisions`** — the append-only **decision journal** (`context/DECISIONS.md`). Use it for decision **history / evolution** — "what did we reject", "did X change", "why did we move away from Y" — it keeps superseded + retracted decisions the live fact store drops. (A plain `cmk search` answers "what's the current decision"; this answers "how it got there".)
 - **`context/memory/<type>_<slug>.md`** — the granular fact archive with full **Why / How** rationale (`context/memory/INDEX.md` lists them).
 - **`~/.claude-memory-kit/` (`USER.md` / `HABITS.md` / `LESSONS.md`)** — how this user works across *all* their projects.