@lh8ppl/claude-memory-kit 0.3.1 → 0.3.3

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,9 +146,132 @@ 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 };
 }
 
+// --- FTS5 query sanitization (Task 153) -------------------------------
+//
+// FTS5's MATCH grammar (sqlite.org/fts5 §3) treats many characters a user
+// would type in a natural query as operators or syntax errors:
+//   - a bareword may ONLY contain letters / digits / underscore / non-ASCII;
+//     a `.`, `-`, `:`, `+`, `^`, `(`, etc. in a bareword is a SYNTAX ERROR.
+//   - `AND` / `OR` / `NOT` (case-sensitive) are reserved boolean operators.
+// So `cmk search v0.3` crashed (`v0` then `.3` → `.` violates the bareword
+// grammar), and `cmk search user-explicit` parsed `-` as a column-exclude.
+//
+// The SQLite-sanctioned fix is to double-quote the offending token: inside a
+// quoted string the tokenizer treats `.`/`-`/`:` as separators, so `"v0.3"`
+// tokenizes to `v0` + `3` and matches the literal content. We quote
+// PER-TOKEN (not the whole query) so a plain multi-word query keeps its
+// implicit-AND semantics (better recall) rather than collapsing to a strict
+// adjacency phrase. A token the user already quoted is left untouched.
+//
+// Validated against the FTS5 spec AND basic-memory's real implementation
+// (the kit's closest FTS5 + markdown-native design analog). Full rationale:
+// docs/research/2026-06-15-fts5-query-preparation-cross-system.md.
+
+// A bareword that FTS5 accepts as-is: letters, digits, underscore, non-ASCII.
+// Anything else in the token means it must be quoted to be a literal.
+const FTS5_BAREWORD_RE = /^[\p{L}\p{N}_]+$/u;
+const FTS5_RESERVED_WORDS = new Set(['AND', 'OR', 'NOT']);
+
+// Quote a single token for literal FTS5 matching, escaping embedded `"`
+// SQL-style (double it) per the spec. Used only when the token isn't a safe
+// bareword.
+function quoteFtsToken(token) {
+  return `"${token.replace(/"/g, '""')}"`;
+}
+
+/**
+ * Transform a raw user query into an FTS5-safe MATCH string.
+ *
+ * Per-token: a safe bareword passes through untouched (preserving
+ * implicit-AND between words); a token with FTS5-special characters or a
+ * bare reserved word (AND/OR/NOT) is double-quoted (literal). A token the
+ * user already wrapped in `"…"` is preserved verbatim — explicit phrase
+ * search still works for power users.
+ *
+ * Exported for isolated unit testing (like reciprocalRankFusion).
+ *
+ * @param {string} raw the user's query
+ * @returns {string} an FTS5-safe MATCH expression ('' for empty input)
+ */
+export function prepareFtsQuery(raw) {
+  if (typeof raw !== 'string') return '';
+  const trimmed = raw.trim();
+  if (trimmed === '') return '';
+
+  return tokenizeQuery(trimmed)
+    .map((token) => {
+      // Already a user-quoted phrase (`"…"`, possibly multi-word): leave it
+      // exactly as typed — explicit phrase search still works for power users.
+      if (token.length >= 2 && token.startsWith('"') && token.endsWith('"')) {
+        return token;
+      }
+      // Safe bareword that isn't a reserved operator: pass through.
+      if (FTS5_BAREWORD_RE.test(token) && !FTS5_RESERVED_WORDS.has(token)) {
+        return token;
+      }
+      // Everything else (special chars, or a bare AND/OR/NOT): quote literal.
+      return quoteFtsToken(token);
+    })
+    .join(' ');
+}
+
+// Split a query into tokens, keeping a double-quoted span (which may contain
+// spaces, e.g. `"thin routes"`) as ONE token. A naive whitespace split would
+// tear `"thin routes"` into `"thin` + `routes"` and corrupt the quoting.
+// Unbalanced trailing quote: the final quoted run extends to end-of-string.
+function tokenizeQuery(query) {
+  const tokens = [];
+  let i = 0;
+  while (i < query.length) {
+    if (/\s/.test(query[i])) {
+      i += 1;
+      continue;
+    }
+    if (query[i] === '"') {
+      // A `"` at a token boundary opens a phrase span: consume up to and
+      // including the closing quote (or end-of-string if unbalanced).
+      let j = i + 1;
+      while (j < query.length && query[j] !== '"') j += 1;
+      const end = j < query.length ? j + 1 : query.length;
+      tokens.push(query.slice(i, end));
+      i = end;
+    } else {
+      // A run of non-space characters. A `"` that appears MID-run (e.g.
+      // `he"llo`) is part of this token, NOT a phrase delimiter — it'll be
+      // escaped + quoted as a literal by prepareFtsQuery. Only whitespace
+      // ends the run.
+      let j = i;
+      while (j < query.length && !/\s/.test(query[j])) j += 1;
+      tokens.push(query.slice(i, j));
+      i = j;
+    }
+  }
+  return tokens;
+}
+
 // --- Keyword (FTS5 BM25) backend --------------------------------------
 
 const KEYWORD_BASE_SQL = `
@@ -158,7 +294,7 @@ WHERE observations_fts MATCH @query
 
 function buildKeywordSql(opts) {
   const clauses = [];
-  const params = { query: opts.query };
+  const params = { query: prepareFtsQuery(opts.query) };
   if (opts.tier !== undefined) {
     clauses.push('o.tier = @tier');
     params.tier = opts.tier;
@@ -265,7 +401,7 @@ function runTranscriptKeywordSearch(db, opts) {
   try {
     rows = db
       .prepare(TRANSCRIPT_KEYWORD_SQL)
-      .all({ query: opts.query, limit: opts.limit ?? DEFAULT_LIMIT });
+      .all({ query: prepareFtsQuery(opts.query), limit: opts.limit ?? DEFAULT_LIMIT });
   } catch (err) {
     if (err?.code === 'SQLITE_ERROR' || /fts5:|no such column:/i.test(err?.message ?? '')) {
       throw new FTS5ParseError(err, opts.query);
@@ -291,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) -----------------------------
 
 /**
@@ -342,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