@lh8ppl/claude-memory-kit 0.1.1 → 0.2.0

package/src/inject-context.mjs

@@ -33,6 +33,24 @@ import { homedir } from 'node:os';
 import { SCRATCHPADS_BY_TIER, resolveTierRoot } from './tier-paths.mjs';
 import { nowIso } from './audit-log.mjs';
 import { detectStaleness } from './lazy-compress.mjs';
+import { isProvenanceCommentLine, parseBulletProvenance } from './provenance.mjs';
+
+// Importance ranking for value-ordered inject eviction (Task 93 / design §19.3).
+// When a tier exceeds its budget we drop the LOWEST-value sections first, not the
+// tail. Trust dominates; recency (newest `at`) breaks ties; a section with no
+// resolvable provenance ranks as UNKNOWN (between low and medium) so genuinely
+// scored content outranks it.
+const TRUST_RANK = Object.freeze({ low: 0, medium: 1, high: 2 });
+const UNKNOWN_TRUST_RANK = 0.5; // a bullet whose provenance we can't read
+function trustRank(trust) {
+  return TRUST_RANK[trust] ?? UNKNOWN_TRUST_RANK;
+}
+function trustLabel(rank) {
+  if (rank >= TRUST_RANK.high) return 'high';
+  if (rank >= TRUST_RANK.medium) return 'medium';
+  if (rank >= UNKNOWN_TRUST_RANK) return 'unknown';
+  return 'low';
+}
 
 // 13,000 bytes = sum of all per-file caps (12,275 from Task 12/14) + 725
 // bytes of headroom for inter-tier markers + future modest growth.
@@ -84,17 +102,20 @@ const TIER_BUDGETS = Object.freeze({
 });
 
 // Per-tier reading plan. The hook reads the scratchpads allowed at that
-// tier (per SCRATCHPADS_BY_TIER) plus the tier's INDEX file, plus — for
-// the project tier — the most recent rolling-window day file.
+// tier (per SCRATCHPADS_BY_TIER) plus — for the project tier — the most
+// recent rolling-window day file.
+//
+// INDEX.md is deliberately NOT in the snapshot (#R, 2026-05-30). It is a
+// pointer/reference doc that self-declares "NOT auto-loaded at session
+// start" in its own template body — injecting it both violated that
+// contract and pushed ~2 KB of reference prose into Claude's context,
+// crowding out real facts. It stays on disk for lookup via `cmk search` /
+// the granular archive; it is not session-start content.
 function plannedFilesForTier(tier, tierRoot) {
   const files = [];
   for (const name of SCRATCHPADS_BY_TIER[tier]) {
     files.push(join(tierRoot, name));
   }
-  // INDEX: P/L use memory/INDEX.md; U uses fragments/INDEX.md (per
-  // resolveFactDir asymmetry in tier-paths.mjs).
-  const indexDir = tier === 'U' ? 'fragments' : 'memory';
-  files.push(join(tierRoot, indexDir, 'INDEX.md'));
   if (tier === 'P') {
     const sessionsDir = join(tierRoot, 'sessions');
     const latest = latestDaySession(sessionsDir);
@@ -138,12 +159,172 @@ function tierDirExists(tier, tierRoot) {
   return existsSync(tierRoot) && statSync(tierRoot).isDirectory();
 }
 
-// Read the snapshot-eligible content for one tier as a single string. If
-// no tier files exist (or the tier dir itself is absent), returns ''. The
-// per-file content is wrapped in a fenced header so the snapshot is
-// self-describing to whoever reads Claude's context window.
+// The all-zero sha1 is the kit's template-seed sentinel: every scaffolded
+// placeholder bullet (in machine-paths/overrides/SOUL/USER/HABITS/LESSONS)
+// carries `sha1: 0000…0000` + `at: 2020-01-01T…`. A real captured fact
+// always has a real content sha1. We use this to distinguish "scaffolding
+// the user never replaced" from "a fact worth injecting".
+const SEED_SHA1_RE = /sha1:\s*0{40}/;
+
+// All HTML-comment handling below uses STRING SCANNING (indexOf/startsWith),
+// never a regex tag-filter. Regex-based HTML-comment stripping is fragile by
+// nature (it can't see newlines, leaves partial `<!--`, etc. — flagged by
+// CodeQL's js/bad-tag-filter). String scanning is both more robust and not a
+// tag-filter, so it sidesteps that whole class.
+
+// True if `line`, ignoring surrounding whitespace, is exactly one self-
+// contained HTML comment (`<!-- … -->`) — e.g. a per-bullet provenance line.
+function isCommentOnlyLine(line) {
+  if (typeof line !== 'string') return false;
+  const t = line.trim();
+  return t.startsWith('<!--') && t.endsWith('-->') && t.length >= 7;
+}
+
+// Remove every self-contained `<!-- … -->` span WITHIN a single line, by
+// scanning for delimiter pairs. An unterminated `<!--` (no `-->` on this
+// line) is left in place for the multi-line state machine to handle.
+function stripInlineComments(line) {
+  let out = '';
+  let i = 0;
+  for (;;) {
+    const open = line.indexOf('<!--', i);
+    if (open === -1) return out + line.slice(i);
+    const close = line.indexOf('-->', open + 4);
+    if (close === -1) return out + line.slice(i); // unterminated; leave it
+    out += line.slice(i, open);
+    i = close + 3;
+  }
+}
+
+// Is `bulletLine` a placeholder/seed bullet that should NOT be injected?
+// Primary signal: a following provenance comment carrying the all-zero seed
+// sha1 (every scaffolded template bullet has it; a real captured fact never
+// does). Secondary: the `(example)` marker — but ONLY in the template's
+// exact `(P-XXXXXXXX) (example) …` shape (right after the citation id), so a
+// real fact whose text merely mentions "(example)" is not mis-dropped.
+function isSeedBullet(bulletLine, nextLine) {
+  if (/^\s*-\s+\([PUL]-[A-Za-z0-9]{8}\)\s+\(example\)/.test(bulletLine)) {
+    return true;
+  }
+  const prov = isCommentOnlyLine(nextLine) ? nextLine : '';
+  return SEED_SHA1_RE.test(prov);
+}
+
+// Remove HTML comments robustly, including the kit templates' multi-line
+// format-explanation headers that ILLUSTRATIVELY embed a single-line
+// `<!-- source… -->` example inside the outer `<!-- … -->` block (a naive
+// "first <!-- to first -->" pass closes on that inner `-->` and orphans the
+// tail). We strip inline comments first (killing the nested one) and only
+// then walk the now-cleanly-delimited multi-line blocks. All string-scan.
+function stripHtmlComments(text) {
+  // Pass 1 — remove every self-contained `<!-- … -->` on a single line.
+  const lines = text.split('\n').map(stripInlineComments);
+  // Pass 2 — remove multi-line blocks (each now free of any inner `-->`).
+  const out = [];
+  let inBlock = false;
+  for (let line of lines) {
+    if (inBlock) {
+      const close = line.indexOf('-->');
+      if (close === -1) continue; // still inside the block; drop the line
+      inBlock = false;
+      line = line.slice(close + 3);
+    }
+    const open = line.indexOf('<!--');
+    if (open !== -1) {
+      inBlock = true;
+      line = line.slice(0, open);
+    }
+    if (line.trim() !== '' || out.length === 0 || out[out.length - 1] !== '') {
+      out.push(line.replace(/[ \t]+$/, ''));
+    }
+  }
+  return out.join('\n');
+}
+
+// Clean a scratchpad body for INJECTION (not for on-disk storage — the
+// files keep their human-editing headers). Self-test finding #R: the raw
+// bodies are ~70% template-comment noise + placeholder seed bullets that
+// bury (and crowd out) the real captured facts, so the model concludes
+// "no real facts populated yet". This strips:
+//   1. placeholder seed bullets (all-zero sha1 / `(example)`) + their
+//      provenance comment line, and
+//   2. ALL remaining `<!-- -->` comments (multi-line format-explanation
+//      headers AND per-bullet provenance — the fact text + its `(P-…)`
+//      citation id carry everything the model needs to read & cite).
+// Whitespace is normalized so stripped regions don't leave holes.
+//
+// Known limitation (rare): a captured fact whose TEXT contains a literal
+// `<!--`/`-->` (e.g. a note about HTML/templating) has that fragment
+// stripped from the INJECTED view. The on-disk fact and the search index
+// are unaffected — only the session-start snapshot loses the literal
+// comment markers. Accepted as a rare edge vs. the cost of distinguishing
+// real comments from comment-shaped fact text.
+function cleanScratchpadBody(body) {
+  // Normalize CRLF so user-edited (Windows) scratchpads don't leave stray
+  // \r after comment/seed stripping.
+  const lines = body.replace(/\r\n/g, '\n').split('\n');
+  const kept = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (
+      /^\s*-\s/.test(line) &&
+      ID_TOKEN_RE.test(line) &&
+      isSeedBullet(line, lines[i + 1])
+    ) {
+      if (isCommentOnlyLine(lines[i + 1])) i++;
+      continue;
+    }
+    kept.push(line);
+  }
+  // Step 2 — strip all remaining comments (format headers + real-bullet
+  // provenance), then normalize whitespace.
+  return stripHtmlComments(kept.join('\n'))
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/^\n+|\n+$/g, '');
+}
+
+// After cleaning, does a body carry any real content — i.e. a non-blank
+// line that isn't a markdown heading? A body of only headings (every
+// bullet was a stripped seed) is pure scaffolding and must NOT contribute
+// a tier block (otherwise the model sees an empty "## …" skeleton).
+function hasRealContent(cleaned) {
+  return cleaned
+    .split('\n')
+    .some((l) => l.trim() !== '' && !/^#{1,6}\s/.test(l));
+}
+
+// Scan a RAW scratchpad body for bullet+provenance pairs, recording each
+// cited id's trust + capture time into `valueById`. Run on the raw body
+// BEFORE cleanScratchpadBody strips the provenance comments — that's the only
+// place the trust/recency signal exists, and the importance-aware truncator
+// (truncateTierToBudget) needs it to rank sections by value, not file order.
+// Note: this records EVERY bullet+provenance pair, including seed bullets (later
+// stripped by cleanScratchpadBody) and ids later removed by cross-tier shadowing.
+// Those stale entries are inert — truncateTierToBudget only resolves ids on block
+// lines that are actually PRESENT, so an orphaned valueById entry is never used.
+function collectBulletValues(body, valueById) {
+  const lines = body.replace(/\r\n/g, '\n').split('\n');
+  for (let i = 0; i < lines.length - 1; i++) {
+    if (!/^\s*-\s/.test(lines[i])) continue;
+    const m = lines[i].match(ID_TOKEN_RE);
+    if (!m) continue;
+    if (!isProvenanceCommentLine(lines[i + 1])) continue;
+    const prov = parseBulletProvenance(lines[i + 1]);
+    if (!prov) continue;
+    valueById.set(`${m[1]}-${m[2]}`, { trust: prov.trust, at: prov.at });
+  }
+}
+
+// Read the snapshot-eligible content for one tier. Returns { text, valueById }.
+// `text` is the cleaned, injection-ready block (or '' if the tier contributes
+// nothing); `valueById` maps each cited id → {trust, at} parsed from the RAW
+// bodies (used by the importance-aware budget truncator). Each file body is
+// cleaned for injection (see cleanScratchpadBody); files that reduce to
+// scaffolding-only contribute nothing, and a tier whose every file is
+// scaffolding-only is excluded entirely (no header, no skeleton).
 function readTierBlock(tier, tierRoot) {
-  if (!tierDirExists(tier, tierRoot)) return '';
+  const valueById = new Map();
+  if (!tierDirExists(tier, tierRoot)) return { text: '', valueById };
   const sections = [];
   for (const path of plannedFilesForTier(tier, tierRoot)) {
     if (!existsSync(path)) continue;
@@ -154,11 +335,21 @@ function readTierBlock(tier, tierRoot) {
       continue;
     }
     if (body.trim() === '') continue;
-    sections.push(body);
+    collectBulletValues(body, valueById); // raw body — provenance still present
+    const cleaned = cleanScratchpadBody(body);
+    if (!hasRealContent(cleaned)) continue;
+    sections.push(cleaned);
   }
-  if (sections.length === 0) return '';
+  if (sections.length === 0) return { text: '', valueById };
   const header = `<!-- cmk: ${TIER_LABELS[tier]} tier (${tier}) -->`;
-  return [header, ...sections].join('\n\n').replace(/\n+$/, '') + '\n';
+  // Trailing-newline strip via string scan (NOT a `/\n+$/` regex — the `+$`
+  // shape trips the ReDoS heuristic, per CLAUDE.md; string-scan is linear and
+  // strips only newlines, faithful to the original intent).
+  const joined = [header, ...sections].join('\n\n');
+  let end = joined.length;
+  while (end > 0 && joined[end - 1] === '\n') end--;
+  const text = joined.slice(0, end) + '\n';
+  return { text, valueById };
 }
 
 // Strip duplicate-ID lines from a tier block. Mutates by returning a new
@@ -178,8 +369,7 @@ function stripShadowedIds(tier, block, seenIds, shadowedEvents, ts) {
       if (prior && prior !== tier) {
         // Drop this line + (if next is the indented provenance) the next.
         const next = lines[i + 1];
-        const isComment =
-          typeof next === 'string' && /^\s*<!--.*-->\s*$/.test(next);
+        const isComment = isProvenanceCommentLine(next);
         // Record the shadowing once per (id, shadowed-tier).
         let event = shadowedEvents.find((e) => e.id === id);
         if (!event) {
@@ -211,27 +401,58 @@ function writeNdjsonLine(logPath, entry) {
   appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf8');
 }
 
-// Truncate one tier block to fit its budget by dropping whole `## `
-// sections from the END. Section-granular (not bullet- or byte-
-// granular) per design §7.1.1: structural shape preservation matters
-// more than maximum byte utilization. Returns { text, sectionsDropped,
-// preBytes, postBytes }.
+// Compute one section's aggregate value from its bullets' provenance.
+// aggregate trust = the MAX bullet trust in the section (so a section holding
+// ANY high-trust bullet is protected before a section that holds none — the
+// §19.3 "never evict a high-trust bullet before a lower one" invariant, at
+// section granularity). aggregate recency = the NEWEST `at`. A section with no
+// resolvable bullets ranks lowest (value -1) so it drops first.
 //
-// Algorithm: split into sections delimited by `## ` (level-2 markdown
-// heading) anywhere in the tier block. Anything BEFORE the first `## `
-// (file headers, comments, top-level title) is the "preamble" and is
-// always kept. Sections are popped from the END until the kept text
-// fits the budget OR no sections remain (preamble-only). If the
-// preamble alone exceeds budget, we return it unchanged — that's a
-// configuration problem (preamble shouldn't be that big) but
-// preferable to dropping the file header.
-function truncateTierToBudget(blockText, budget) {
+// Known limitation (section-granularity, accepted per §7.1.1 + the Task 93
+// "whole sections by aggregate value" sanction): MAX-aggregate protects high-
+// trust content, but a LOW-trust bullet bundled in the same section as a high-
+// trust one survives, while a standalone MEDIUM-trust section can be dropped
+// first — a bullet-level inversion. Note the asymmetry with 94.3 graduation,
+// which evicts per-BULLET (oldest-first). Bullet-granular inject eviction is the
+// stricter v-next option if this matters; for now it keeps §7.1.1 structural
+// shape + costs less re-rendering.
+function sectionValue(lines, startIdx, endIdx, valueById) {
+  let maxTrust = -1;
+  let maxAtMs = -1;
+  const ids = [];
+  for (let i = startIdx; i < endIdx; i++) {
+    if (!/^\s*-\s/.test(lines[i])) continue;
+    const m = lines[i].match(ID_TOKEN_RE);
+    if (!m) continue;
+    const id = `${m[1]}-${m[2]}`;
+    ids.push(id);
+    const v = valueById.get(id);
+    const t = v ? trustRank(v.trust) : UNKNOWN_TRUST_RANK;
+    if (t > maxTrust) maxTrust = t;
+    const atMs = v && v.at ? Date.parse(v.at) : NaN;
+    if (!Number.isNaN(atMs) && atMs > maxAtMs) maxAtMs = atMs;
+  }
+  return { maxTrust, maxAtMs, ids };
+}
+
+// Truncate one tier block to fit its budget by dropping whole `## ` sections,
+// LOWEST-VALUE first (Task 93 / design §19.3) — superseding the old tail-order
+// drop. Section-granular per design §7.1.1 (structural-shape preservation), but
+// the eviction ORDER is now importance-aware: lowest aggregate trust first, then
+// oldest, then — as a tiebreak among equal-value sections — later-in-file first.
+// That tiebreak makes this a strict generalization of the legacy tail-drop: when
+// no provenance is present (every section ranks equal) it drops from the end,
+// exactly as before. Returns { text, sectionsDropped, droppedSections, preBytes,
+// postBytes }.
+//
+// Anything BEFORE the first `## ` (file headers, top-level title) is the
+// "preamble" and always kept; if the preamble alone exceeds budget it's returned
+// unchanged (a config problem, but preferable to dropping the header).
+function truncateTierToBudget(blockText, budget, valueById = new Map()) {
   const preBytes = Buffer.byteLength(blockText, 'utf8');
   if (preBytes <= budget) {
-    return { text: blockText, sectionsDropped: 0, preBytes, postBytes: preBytes };
+    return { text: blockText, sectionsDropped: 0, droppedSections: [], preBytes, postBytes: preBytes };
   }
-  // Find every `## ` heading position. Each section runs from one
-  // heading line to the next (or EOF).
   const lines = blockText.split('\n');
   const headingIdxs = [];
   for (let i = 0; i < lines.length; i++) {
@@ -239,27 +460,51 @@ function truncateTierToBudget(blockText, budget) {
   }
   if (headingIdxs.length === 0) {
     // No sections — nothing to drop. Return as-is.
-    return { text: blockText, sectionsDropped: 0, preBytes, postBytes: preBytes };
+    return { text: blockText, sectionsDropped: 0, droppedSections: [], preBytes, postBytes: preBytes };
   }
-  // Build section boundaries: [start..end) for each section.
-  const sections = headingIdxs.map((startIdx, i) => ({
-    startIdx,
-    endIdx: i + 1 < headingIdxs.length ? headingIdxs[i + 1] : lines.length,
-  }));
-  // Pop from the end while over budget.
-  let droppedCount = 0;
-  let keptEndLine = lines.length;
-  while (sections.length > 0) {
-    const candidateText = lines.slice(0, keptEndLine).join('\n');
-    if (Buffer.byteLength(candidateText, 'utf8') <= budget) break;
-    const last = sections.pop();
-    keptEndLine = last.startIdx;
-    droppedCount++;
+  const firstHeading = headingIdxs[0];
+  const sections = headingIdxs.map((startIdx, i) => {
+    const endIdx = i + 1 < headingIdxs.length ? headingIdxs[i + 1] : lines.length;
+    return {
+      origIndex: i,
+      startIdx,
+      endIdx,
+      heading: lines[startIdx].replace(/^##\s+/, '').trim(),
+      ...sectionValue(lines, startIdx, endIdx, valueById),
+    };
+  });
+  // Drop order: lowest aggregate trust first → oldest first → later-in-file
+  // first (the legacy tail tiebreak, so equal-value blocks still drop from the
+  // end). High-value sections are evicted only after everything cheaper is gone.
+  const dropOrder = [...sections].sort(
+    (a, b) =>
+      a.maxTrust - b.maxTrust ||
+      a.maxAtMs - b.maxAtMs ||
+      b.origIndex - a.origIndex,
+  );
+  const dropped = new Set();
+  const render = () => {
+    const keep = [];
+    for (let i = 0; i < firstHeading; i++) keep.push(lines[i]); // preamble
+    for (const s of sections) {
+      if (dropped.has(s.origIndex)) continue;
+      for (let i = s.startIdx; i < s.endIdx; i++) keep.push(lines[i]);
+    }
+    return keep.join('\n');
+  };
+  let finalText = render();
+  for (const s of dropOrder) {
+    if (Buffer.byteLength(finalText, 'utf8') <= budget) break;
+    dropped.add(s.origIndex);
+    finalText = render();
   }
-  const finalText = lines.slice(0, keptEndLine).join('\n');
+  const droppedSections = sections
+    .filter((s) => dropped.has(s.origIndex))
+    .map((s) => ({ heading: s.heading, max_trust: trustLabel(s.maxTrust), ids: s.ids }));
   return {
     text: finalText,
-    sectionsDropped: droppedCount,
+    sectionsDropped: dropped.size,
+    droppedSections,
     preBytes,
     postBytes: Buffer.byteLength(finalText, 'utf8'),
   };
@@ -281,7 +526,7 @@ function enforceCap(orderedBlocks, capBytes, ts) {
   for (const block of orderedBlocks) {
     const budget = TIER_BUDGETS[block.tier];
     if (typeof budget !== 'number') continue; // unknown tier; pass through
-    const r = truncateTierToBudget(block.text, budget);
+    const r = truncateTierToBudget(block.text, budget, block.valueById);
     if (r.sectionsDropped > 0) {
       tierEvents.push({
         ts,
@@ -291,6 +536,11 @@ function enforceCap(orderedBlocks, capBytes, ts) {
         pre_bytes: r.preBytes,
         post_bytes: r.postBytes,
         sections_dropped: r.sectionsDropped,
+        // Door 4 (Task 93): WHICH sections were evicted + WHY (lowest-value
+        // first). dropped_sections carries each evicted section's heading, its
+        // aggregate trust, and the cited ids it contained.
+        strategy: 'importance-ordered',
+        dropped_sections: r.droppedSections,
       });
       block.text = r.text;
     }
@@ -330,23 +580,52 @@ function enforceCap(orderedBlocks, capBytes, ts) {
  * Exposed so injectContext can override via dependency injection in tests
  * (testSpawnLazy parameter) — production callers pass nothing.
  */
-function spawnLazyCompress(projectRoot) {
+/**
+ * Pure spawn descriptor for the lazy-compress child (Task 81). Separated so the
+ * Door-3 contract (node-direct + windowsHide, no shell, when the path is known)
+ * is unit-assertable without a real spawn. Path known + present → `node <path>`
+ * directly; otherwise the PATH-resolved `.cmd` bin via shell:true (the corrupt-
+ * install fallback that may still flash a console on Windows).
+ */
+export function lazyCompressSpawnDescriptor(projectRoot, compressLazyPath) {
+  const baseEnv = { ...process.env, CMK_PROJECT_DIR: projectRoot };
+  if (compressLazyPath && existsSync(compressLazyPath)) {
+    return {
+      command: process.execPath,
+      args: [compressLazyPath],
+      options: { detached: true, stdio: 'ignore', cwd: projectRoot, windowsHide: true, env: baseEnv },
+    };
+  }
+  return {
+    command: 'cmk-compress-lazy',
+    args: [],
+    options: { detached: true, stdio: 'ignore', shell: true, cwd: projectRoot, windowsHide: true, env: baseEnv },
+  };
+}
+
+function spawnLazyCompress(projectRoot, compressLazyPath) {
   try {
     // The lazy-compress child intentionally outlives this hook process;
     // parent-side timeout is incorrect by design — the child carries its
     // own internal timeout via runLazyCompress → daily-distill /
     // weekly-curate → HaikuViaAnthropicApi.compress({timeoutMs: 50_000}).
-    // shell:true so the Windows .cmd shim is found via PATH (same pattern
-    // register-crons.mjs uses for cmk-daily-distill).
     // spawn-discipline: ignore detached-fire-and-forget per design §8.5 — same posture as capture-turn.mjs's auto-extract spawn (Task 23).
-    const child = spawn('cmk-compress-lazy', [], {
-      detached: true,
-      stdio: 'ignore',
-      shell: true,
-      cwd: projectRoot,
-      windowsHide: true,
-      env: { ...process.env, CMK_PROJECT_DIR: projectRoot },
-    });
+    //
+    // Task 81 (Windows console-popup fix): spawn `node` DIRECTLY on the
+    // resolved .mjs. The legacy `shell:true` path resolved the npm `.cmd`
+    // shim via cmd.exe (cmd.exe → cmk-compress-lazy.cmd → node), and on
+    // Windows `windowsHide:true` hid only the cmd.exe window — NOT the
+    // detached `node` grandchild the shim launched, which flashed a visible
+    // console at every SessionStart. `process.execPath` + `windowsHide`
+    // suppresses it. The shell:true bin-name spawn survives only as a
+    // fallback when the path is unknown (corrupt install) — better the
+    // legacy popup than losing compression entirely.
+    const { command, args, options } = lazyCompressSpawnDescriptor(
+      projectRoot,
+      compressLazyPath,
+    );
+    // spawn-discipline: ignore detached fire-and-forget per design §8.5 — the child carries its own internal timeout (runLazyCompress → compress({timeoutMs})); parent-side timeout is incorrect by design.
+    const child = spawn(command, args, options);
     child.unref();
     return { spawned: true, pid: child.pid };
   } catch (err) {
@@ -387,6 +666,11 @@ export function injectContext({
   // uses spawnLazyCompress directly). Tests pass a fake to assert
   // "lazy-compress was/was-not triggered" without touching the host.
   testSpawnLazy,
+  // Resolved path to cmk-compress-lazy.mjs (passed by the bin wrapper, which
+  // knows the install layout). Lets spawnLazyCompress run `node <path>`
+  // directly instead of the shell:true `.cmd` shim — the Windows
+  // console-popup fix (Task 81). Absent → graceful shell:true fallback.
+  compressLazyPath,
 } = {}) {
   const ts = now ?? nowIso();
   const cap = typeof capBytes === 'number' ? capBytes : DEFAULT_CAP_BYTES;
@@ -397,13 +681,16 @@ export function injectContext({
     process.env.MEMORY_KIT_USER_DIR ??
     join(homedir(), '.claude-memory-kit');
 
-  // 1. Read each tier's block in priority order.
+  // 1. Read each tier's block in priority order. readTierBlock also returns a
+  // per-tier value map (id → trust/recency) parsed from the raw bodies, which
+  // the importance-aware budget truncator uses to evict lowest-value first.
   const rawBlocks = TIER_ORDER.map((tier) => {
     const tierRoot =
       tier === 'U'
         ? resolvedUserDir
         : resolveTierRoot({ tier, projectRoot, userDir: resolvedUserDir });
-    return { tier, tierRoot, text: readTierBlock(tier, tierRoot) };
+    const { text, valueById } = readTierBlock(tier, tierRoot);
+    return { tier, tierRoot, text, valueById };
   }).filter((b) => b.text !== '');
 
   // 2. Dedup IDs across tiers (highest-priority first).
@@ -455,7 +742,7 @@ export function injectContext({
     lazyTrigger = { verdict: verdict.action, reason: verdict.reason };
     if (verdict.action === 'stale-daily' || verdict.action === 'stale-weekly') {
       const spawner = typeof testSpawnLazy === 'function' ? testSpawnLazy : spawnLazyCompress;
-      const spawnResult = spawner(projectRoot);
+      const spawnResult = spawner(projectRoot, compressLazyPath);
       lazyTrigger = { ...lazyTrigger, ...spawnResult };
     }
   } catch (err) {

package/src/install.mjs

@@ -37,10 +37,9 @@ import {
   readdirSync,
   statSync,
   writeFileSync,
-  copyFileSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { injectClaudeMdBlock } from './claude-md.mjs';
 import { writeKitHooks } from './settings-hooks.mjs';
@@ -155,7 +154,27 @@ function targetName(srcName) {
  *   - Writes new files
  *   - Mutates the supplied `created` / `skipped` / `errors` arrays
  */
-function installTier(srcDir, destDir, { created, skipped, errors }) {
+// Substitute the kit's template placeholders. Templates ship with
+// `{{TODAY}}` / `{{PROJECT_NAME}}` / `{{VERSION}}`; without this, the
+// scaffolded scratchpads leaked a literal `{{TODAY}}` into MEMORY.md et al.
+// (live-test finding #4). Only the three known tokens are replaced.
+function renderTemplate(content, vars) {
+  return content
+    .replaceAll('{{TODAY}}', vars.today)
+    .replaceAll('{{PROJECT_NAME}}', vars.projectName)
+    .replaceAll('{{VERSION}}', vars.version);
+}
+
+function installTier(srcDir, destDir, { created, skipped, errors, vars }) {
+  // Self-sufficient default so no caller can crash renderTemplate by omitting
+  // vars (e.g. initUserTier). install() passes an explicit vars with the real
+  // projectName; standalone callers fall back to a sensible default (the user
+  // tier's scratchpads only carry {{TODAY}} anyway).
+  const v = vars ?? {
+    today: new Date().toISOString().slice(0, 10),
+    projectName: basename(destDir),
+    version: getKitVersion(),
+  };
   if (!existsSync(srcDir)) {
     errors.push({ path: srcDir, error: 'template tier missing from kit' });
     return;
@@ -182,7 +201,10 @@ function installTier(srcDir, destDir, { created, skipped, errors }) {
 
     try {
       mkdirSync(dirname(targetAbs), { recursive: true });
-      copyFileSync(file.absSrc, targetAbs);
+      // Read → render placeholders → write (was a raw copyFileSync, which left
+      // `{{TODAY}}` literal in the scaffolded scratchpads). All template files
+      // are text (.gitkeep is handled above), so utf8 round-trip is safe.
+      writeFileSync(targetAbs, renderTemplate(readFileSync(file.absSrc, 'utf8'), v), 'utf8');
       created.push(targetAbs);
     } catch (err) {
       errors.push({ path: targetAbs, error: err && err.message ? err.message : String(err) });
@@ -269,9 +291,32 @@ export async function install(options = {}) {
   const skipped = [];
   const errors = [];
 
-  installTier(join(templateDir, 'project'), join(projectRoot, 'context'), { created, skipped, errors });
-  installTier(join(templateDir, 'local'), join(projectRoot, 'context.local'), { created, skipped, errors });
-  installTier(join(templateDir, 'user'), userTier, { created, skipped, errors });
+  const vars = {
+    today: new Date().toISOString().slice(0, 10), // YYYY-MM-DD
+    projectName: basename(projectRoot),
+    version,
+  };
+
+  installTier(join(templateDir, 'project'), join(projectRoot, 'context'), { created, skipped, errors, vars });
+  installTier(join(templateDir, 'local'), join(projectRoot, 'context.local'), { created, skipped, errors, vars });
+  installTier(join(templateDir, 'user'), userTier, { created, skipped, errors, vars });
+
+  // Skills — Task 69. Scaffold the kit's Claude Code skills from
+  // template/.claude/skills/ into <projectRoot>/.claude/skills/. This is what
+  // makes model-invoked capture (the memory-write skill) ship with the npm
+  // `cmk install` route, not only the plugin route — route-equivalence per
+  // design §1.3. Same boundary as the tiers: idempotent skip-existing +
+  // over-mutation-safe (a hand-edited skill survives a re-install). The skill
+  // files carry no {{placeholders}}, so renderTemplate is a byte-passthrough.
+  const skillsSrc = join(templateDir, '.claude', 'skills');
+  if (existsSync(skillsSrc)) {
+    installTier(skillsSrc, join(projectRoot, '.claude', 'skills'), {
+      created,
+      skipped,
+      errors,
+      vars,
+    });
+  }
 
   const gitignore = injectGitignore(projectRoot, buildGitignoreBlock(templateDir));