@lh8ppl/claude-memory-kit 0.1.2 → 0.2.1

package/src/graduation.mjs

@@ -0,0 +1,179 @@
+// graduation.mjs — Task 91 (D-54 / D-57). The 3rd MEMORY.md shrink mechanism.
+//
+// When appendScratchpadBullet() hits cap pressure and consolidate() (stale-drop)
+// can't free enough — because high-trust bullets are NEVER dropped — graduation
+// moves the OLDEST high-trust bullets OUT of the byte-capped hot index into the
+// permanent, indexed fact store (context/memory/<type>_<slug>.md via writeFact),
+// so the new write lands instead of returning CAP_EXCEEDED.
+//
+// Decision A (D-57): SEARCH-ONLY (graduated facts are not injected; reliable
+// recall of them is Task 75, v0.3) and PROJECT MEMORY.md ONLY — the caller gates
+// the tier/scratchpad so this never fires on user-tier persona scratchpads.
+//
+// Reuses writeFact(), which gives four lifecycle-edge guarantees for free:
+//   - cross-store dedup (content-id keyed → re-graduating the same fact is a
+//     no-op `skipped`, not a duplicate file),
+//   - home-path sanitization + Poison_Guard (the safe write path),
+//   - reindex-on-write (the FTS5/INDEX.md view stays consistent — map edge #8).
+
+import { unlinkSync } from 'node:fs';
+import { writeFact } from './write-fact.mjs';
+import { reindex } from './reindex.mjs';
+import { parseBulletProvenance, isProvenanceCommentLine } from './provenance.mjs';
+
+// Loose enough to match whatever id a bullet carries (graduation moves the
+// bullet regardless of id-alphabet validity; that's the writer's concern).
+const BULLET_RE = /^- \(([PUL]-[A-Za-z0-9]+)\)\s*(.*)$/;
+
+const VALID_WRITE_SOURCES = new Set([
+  'user-explicit',
+  'auto-extract',
+  'compressor',
+  'manual-edit',
+  'imported',
+]);
+
+function slugify(s) {
+  // Collapse non-alphanumerics to single dashes, cap, trim edges (string ops,
+  // no trailing-dash quantifier — matches subcommands.slugifyFact's ReDoS-safe
+  // shape).
+  let base = String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 40);
+  if (base.startsWith('-')) base = base.slice(1);
+  if (base.endsWith('-')) base = base.slice(0, -1);
+  return base || 'fact';
+}
+
+function deriveTitle(text) {
+  const t = String(text).trim().slice(0, 80).trim();
+  return t || 'graduated fact';
+}
+
+// One bullet → one project-tier fact file. writeFact action 'error' means it
+// could NOT be stored (collision / poison / schema) → the caller must keep the
+// bullet; anything else ('created' or a dedup 'skipped') means it's safely in
+// the permanent store → the caller removes the bullet from the hot index.
+function graduateOne({ id, text, prov, tier, projectRoot, userDir, now }) {
+  // Slug carries a content-derived tail so two distinct facts never collide on
+  // `project_<slug>.md`, while the SAME fact re-graduates to the same filename
+  // (→ writeFact dedups by id instead of creating a duplicate).
+  const slugTail = id.replace(/^[PUL]-/, '').toLowerCase();
+  return writeFact({
+    tier,
+    // User-tier graduated content is cross-project doctrine → 'user'; project
+    // (and any other) tier → 'project'. Both are valid fact-file types; this
+    // just keeps the on-disk filename + frontmatter semantically honest.
+    type: tier === 'U' ? 'user' : 'project',
+    slug: `${slugify(text)}-${slugTail}`,
+    title: deriveTitle(text),
+    body: text,
+    writeSource: VALID_WRITE_SOURCES.has(prov.write) ? prov.write : 'manual-edit',
+    trust: 'high',
+    sourceFile: prov.source || 'MEMORY.md',
+    sourceLine: prov.source_line || 1,
+    sourceSha1: prov.sha1,
+    id, // preserve the citation id across graduation; also the dedup key
+    createdAt: prov.at, // keep the original capture time
+    projectRoot,
+    userDir,
+    now,
+  });
+}
+
+/**
+ * Graduate oldest high-trust bullets out of `text` until it fits `capBytes`.
+ *
+ * @returns {{ text: string, graduated: string[] }} the new scratchpad content
+ *   (graduated bullets removed) and the ids that were graduated.
+ */
+export function graduateForCapRelief({
+  text,
+  capBytes,
+  tier,
+  projectRoot,
+  userDir,
+  now,
+}) {
+  const lines = text.split('\n');
+  const entries = [];
+  for (let i = 0; i < lines.length - 1; i++) {
+    const m = lines[i].match(BULLET_RE);
+    if (!m) continue;
+    if (!isProvenanceCommentLine(lines[i + 1])) continue;
+    const prov = parseBulletProvenance(lines[i + 1]);
+    if (!prov || prov.trust !== 'high' || !prov.at) continue;
+    entries.push({ bulletIdx: i, commentIdx: i + 1, id: m[1], text: m[2], prov });
+  }
+  // Feasibility gate (composition safety): if graduating EVERY eligible bullet
+  // still wouldn't get under cap, graduate NOTHING. Otherwise writeFact would
+  // persist fact files that the failed-append error path then strands — the
+  // bullets stay in the unchanged on-disk MEMORY.md AND now also exist as fact
+  // files: the exact double-capture this task exists to kill. Returning early
+  // lets CAP_EXCEEDED fire cleanly with zero side effects.
+  const bulletBytes = (e) =>
+    Buffer.byteLength(`${lines[e.bulletIdx]}\n${lines[e.commentIdx]}\n`, 'utf8');
+  const totalGraduatable = entries.reduce((sum, e) => sum + bulletBytes(e), 0);
+  const startBytes = Buffer.byteLength(text, 'utf8');
+  if (startBytes - totalGraduatable > capBytes) {
+    return { text, graduated: [] };
+  }
+
+  // Oldest first: graduate aged durable facts before recent ones. The just-
+  // appended bullet (newest `at`) sorts last and only graduates if still needed.
+  entries.sort(
+    (a, b) => new Date(a.prov.at).getTime() - new Date(b.prov.at).getTime(),
+  );
+
+  const removeIdx = new Set();
+  const graduated = [];
+  const createdPaths = []; // files writeFact NEWLY created (for transactional rollback)
+  let curBytes = Buffer.byteLength(text, 'utf8');
+  for (const e of entries) {
+    if (curBytes <= capBytes) break;
+    const res = graduateOne({
+      id: e.id,
+      text: e.text,
+      prov: e.prov,
+      tier,
+      projectRoot,
+      userDir,
+      now,
+    });
+    if (res.action === 'error') continue; // couldn't store → keep the bullet
+    // 'created' made a NEW file (track for rollback); 'skipped' deduped against
+    // a pre-existing fact file (don't track — deleting it would lose a real fact).
+    if (res.action === 'created' && res.path) createdPaths.push(res.path);
+    removeIdx.add(e.bulletIdx);
+    removeIdx.add(e.commentIdx);
+    graduated.push(e.id);
+    curBytes -= bulletBytes(e);
+  }
+
+  // Transactional guard (composition safety): the feasibility gate assumed every
+  // eligible bullet would graduate. If a graduateOne unexpectedly errored
+  // (poison/schema on a resident bullet) we may still be over cap — the append
+  // will then CAP_EXCEEDED and leave MEMORY.md unchanged, which would STRAND the
+  // fact files we created (the bullets stay live AND now exist as facts = the
+  // double-capture this task kills). Roll the created files back so the failure
+  // path has zero side effects, and let CAP_EXCEEDED fire cleanly.
+  if (curBytes > capBytes) {
+    for (const p of createdPaths) {
+      try {
+        unlinkSync(p);
+      } catch {
+        // best-effort; a leaked fact file is recoverable, a lost bullet is not
+      }
+    }
+    if (createdPaths.length > 0) {
+      try {
+        reindex({ tier, projectRoot, userDir, warn: () => {} });
+      } catch {
+        // index rebuild is best-effort; the next reindex/search self-heals
+      }
+    }
+    return { text, graduated: [] };
+  }
+
+  if (removeIdx.size === 0) return { text, graduated: [] };
+  const out = lines.filter((_, i) => !removeIdx.has(i)).join('\n');
+  return { text: out, graduated };
+}

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.
@@ -275,13 +293,38 @@ function hasRealContent(cleaned) {
     .some((l) => l.trim() !== '' && !/^#{1,6}\s/.test(l));
 }
 
-// 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 ''. 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).
+// 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;
@@ -292,13 +335,21 @@ function readTierBlock(tier, tierRoot) {
       continue;
     }
     if (body.trim() === '') continue;
+    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
@@ -318,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) {
@@ -351,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.
+//
+// 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 }.
 //
-// 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) {
+// 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++) {
@@ -379,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'),
   };
@@ -421,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,
@@ -431,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;
     }
@@ -470,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) {
@@ -527,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;
@@ -537,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).
@@ -595,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));