@lh8ppl/claude-memory-kit 0.3.2 → 0.3.4

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;
@@ -330,6 +411,11 @@ export async function runLazyCompress({
       backend,
       now: ts,
       cooldownMs: 0,
+      // Task 161 / D-175: the lazy path is a DETACHED SessionStart child with NO 60s
+      // hook ceiling, so it opts into the one retry the hook path can't afford. This
+      // is where the SessionEnd-hook's failed roll (which restored now.md, D-79) gets
+      // its real bounded retry.
+      maxAttempts: 2,
     });
   } else if (verdict.action === 'stale-weekly') {
     delegatedTo = 'weekly-curate';

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