@polymorphism-tech/morph-spec 4.9.0 → 4.10.0

package/framework/hooks/claude-code/post-tool-use/skill-reminder.js

@@ -18,83 +18,13 @@
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { readStdin } from '../../shared/stdin-reader.js';
-import { stateExists } from '../../shared/state-reader.js';
+import { stateExists, loadState, derivePhaseForFeature } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
+import { parseTaskStartCommand, buildSkillReminderMessage } from '../../shared/skill-reminder-helpers.js';
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Pure helpers (exported for testing)
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Parse `morph-spec task start <feature> <taskId>` from a bash command string.
- * Returns { featureName, taskId } or null if the command doesn't match.
- *
- * @param {string} command
- * @returns {{ featureName: string, taskId: string } | null}
- */
-export function parseTaskStartCommand(command) {
-  if (!command || typeof command !== 'string') return null;
-  const match = command.match(/morph-spec\s+task\s+start\s+(\S+)\s+(\S+)/);
-  if (!match) return null;
-  return { featureName: match[1], taskId: match[2] };
-}
-
-/**
- * Build the mandatory skill reminder message for a task start event.
- * Returns null if no relevant skills exist for this phase.
- *
- * @param {string} featureName
- * @param {string} taskId
- * @param {string} phase
- * @param {Object|null} phasesData - Parsed phases.json content
- * @returns {string|null}
- */
-export function buildSkillReminderMessage(featureName, taskId, phase, phasesData) {
-  try {
-    const allSkills = phasesData?.phases?.[phase]?.requiredSkills;
-    if (!allSkills || allSkills.length === 0) return null;
-
-    const nowSkills   = allSkills.filter(s => s.trigger === 'beforeEachTask');
-    const laterSkills = allSkills.filter(s => s.trigger === 'beforeTaskDone');
-    const bugSkills   = allSkills.filter(s => s.trigger === 'onBugOrUnexpected');
-
-    if (nowSkills.length === 0 && laterSkills.length === 0) return null;
-
-    const lines = [];
-    lines.push(`⚠️  MORPH-SPEC SKILL REMINDER — Task ${taskId} started (phase: ${phase})`);
-    lines.push('');
-
-    if (nowSkills.length > 0) {
-      lines.push('INVOKE NOW before writing any code:');
-      for (const s of nowSkills) {
-        lines.push(`  → Skill(${s.skill})`);
-      }
-      lines.push('');
-    }
-
-    if (laterSkills.length > 0) {
-      lines.push('INVOKE BEFORE marking task done:');
-      for (const s of laterSkills) {
-        lines.push(`  → Skill(${s.skill})`);
-      }
-      lines.push('');
-    }
-
-    if (bugSkills.length > 0) {
-      lines.push('IF you encounter a bug or unexpected behavior:');
-      for (const s of bugSkills) {
-        lines.push(`  → Skill(${s.skill})`);
-      }
-      lines.push('');
-    }
-
-    lines.push('These are MANDATORY. Use the Skill() tool. Do NOT skip.');
-    return lines.join('\n');
-  } catch {
-    return null;
-  }
-}
+// Re-export for backwards compatibility (tests may import from this file)
+export { parseTaskStartCommand, buildSkillReminderMessage };
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Hook entry point
@@ -113,20 +43,13 @@ try {
   const { featureName, taskId } = parsed;
 
   // Load state to get current phase
-  const statePath = join(process.cwd(), '.morph', 'state.json');
-  if (!existsSync(statePath)) pass();
-
-  let state;
-  try {
-    state = JSON.parse(readFileSync(statePath, 'utf8'));
-  } catch {
-    pass();
-  }
+  const state = loadState();
+  if (!state) pass();
 
   const feature = state?.features?.[featureName];
   if (!feature) pass();
 
-  const phase = feature.phase;
+  const phase = feature.phase || derivePhaseForFeature(featureName);
   if (!phase) pass();
 
   // Load phases.json (project-local first, fall back to package-level)

package/framework/hooks/claude-code/post-tool-use/validator-feedback.js

@@ -16,12 +16,11 @@
  * Fail-open: exits 0 on any error.
  */
 
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
 import { readStdin } from '../../shared/stdin-reader.js';
-import { stateExists } from '../../shared/state-reader.js';
+import { stateExists, loadState } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
+import { parseTaskDoneCommand } from '../../shared/dispatch-helpers.js';
 
 // Standard IDs referenced in remediation messages
 const STANDARD_REFS = {
@@ -42,22 +41,14 @@ try {
   const command = payload?.tool_input?.command || '';
   if (!command) pass();
 
-  // Match: morph-spec task done <feature> <taskId>
-  const taskDoneMatch = command.match(/morph-spec\s+task\s+done\s+(\S+)\s+(\S+)/);
-  if (!taskDoneMatch) pass();
+  const parsed = parseTaskDoneCommand(command);
+  if (!parsed) pass();
 
-  const [, featureName, taskId] = taskDoneMatch;
+  const { featureName, taskId } = parsed;
 
   // Load state and find validationHistory for this task
-  const statePath = join(process.cwd(), '.morph', 'state.json');
-  if (!existsSync(statePath)) pass();
-
-  let state;
-  try {
-    state = JSON.parse(readFileSync(statePath, 'utf8'));
-  } catch {
-    pass();
-  }
+  const state = loadState();
+  if (!state) pass();
 
   const feature = state?.features?.[featureName];
   if (!feature) pass();
@@ -100,7 +91,7 @@ function buildRemediationContext(featureName, taskId, taskHistory) {
     }
   }
 
-  if (allIssues.length === 0 && taskHistory.status !== 'blocked') pass();
+  if (allIssues.length === 0 && taskHistory.status !== 'blocked') return;
 
   const lines = [];
 

package/framework/hooks/claude-code/pre-compact/save-morph-context.js

@@ -23,9 +23,7 @@ import {
 } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
-
-const DECISIONS_MAX_CHARS = 1500;
-const MAX_PENDING_TASKS   = 8;
+import { buildRichContext, DECISIONS_MAX_CHARS, MAX_PENDING_TASKS } from '../../shared/compact-restore.js';
 
 const PHASE_POSITIONS = {
   proposal: 1, setup: 1,
@@ -73,6 +71,21 @@ try {
     };
   }
 
+  // ── Enrich snapshot with richContext (decisions + taskList) ───────────────
+  if (active) {
+    try {
+      const { name: activeName, feature: activeFeature } = active;
+      const activePhase = derivePhaseForFeature(activeName);
+      let decisionsContent = '';
+      const decisionsPath = join(cwd, `.morph/features/${activeName}/1-design/decisions.md`);
+      if (existsSync(decisionsPath)) {
+        try { decisionsContent = readFileSync(decisionsPath, 'utf-8'); } catch { /* ignore */ }
+      }
+      snapshot.richContext = buildRichContext(activeFeature, activePhase, decisionsContent);
+    } catch { /* fail-open: richContext is optional */ }
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+
   const memoryDir = join(cwd, '.morph', 'memory');
   if (!existsSync(memoryDir)) mkdirSync(memoryDir, { recursive: true });
   const ts = new Date().toISOString().replace(/[:.]/g, '-');

package/framework/hooks/claude-code/pre-tool-use/enforce-phase-writes.js

@@ -9,8 +9,8 @@
  *   proposal → only 0-proposal/
  *   design, clarify → only 1-design/
  *   uiux → only 2-ui/
- *   tasks → only 3-tasks/
- *   implement → 4-implement/ + any source code (unrestricted)
+ *   tasks → only 4-tasks/
+ *   implement → 5-implement/ + any source code (unrestricted)
  *
  * Files outside .morph/features/ are always allowed.
  *
@@ -29,6 +29,7 @@ import {
 } from '../../shared/phase-utils.js';
 import { block, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
+import { getFilePath } from '../../shared/payload-utils.js';
 
 try {
   // Amend mode: bypass phase write enforcement for legitimate corrections
@@ -42,7 +43,7 @@ try {
   const payload = await readStdin();
   if (!payload) pass();
 
-  const filePath = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
+  const filePath = getFilePath(payload);
   if (!filePath) pass();
 
   // Only check files inside .morph/features/

package/framework/hooks/claude-code/pre-tool-use/protect-spec-files.js

@@ -7,7 +7,7 @@
  *
  * Blocks Write/Edit to spec artifacts after their approval gate has passed:
  *   - 1-design/spec.md, contracts.cs, etc. → blocked if 'design' gate approved
- *   - 3-tasks/tasks.md → blocked if 'tasks' gate approved
+ *   - 4-tasks/tasks.md → blocked if 'tasks' gate approved
  *   - 2-ui/design-system.md, etc. → blocked if 'uiux' gate approved
  *
  * Fail-open: exits 0 on any error.
@@ -23,6 +23,7 @@ import {
 } from '../../shared/phase-utils.js';
 import { block, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
+import { getFilePath } from '../../shared/payload-utils.js';
 
 try {
   // Amend mode: bypass spec protection for legitimate in-implementation corrections
@@ -36,7 +37,7 @@ try {
   const payload = await readStdin();
   if (!payload) pass();
 
-  const filePath = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
+  const filePath = getFilePath(payload);
   if (!filePath) pass();
 
   // Only check files inside .morph/features/

package/framework/hooks/claude-code/pre-tool-use/task-tracking-guard.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse Hook: Advisory Task Tracking Guard
+ *
+ * Event: PreToolUse | Matcher: Write|Edit
+ *
+ * During implement phase, injects a warning if no task is currently in_progress.
+ * Advisory only (type: approve with context) — never blocks.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists, loadState, getActiveFeature, derivePhaseForFeature } from '../../shared/state-reader.js';
+import { approve, pass } from '../../shared/hook-response.js';
+import { getFilePath } from '../../shared/payload-utils.js';
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Skip files inside .morph/ — internal framework writes don't need task tracking
+  if (filePath.includes('.morph/') || filePath.includes('.morph\\')) pass();
+
+  // Only check during implement phase
+  const active = getActiveFeature();
+  if (!active) pass();
+
+  const { name, feature } = active;
+  const phase = feature.phase || derivePhaseForFeature(name);
+  if (phase !== 'implement') pass();
+
+  // Check if any task is in_progress
+  // Method 1: tasks.inProgress counter (v3 state format)
+  if (feature.tasks?.inProgress > 0) pass();
+
+  // Method 2: taskList array (v2 state format)
+  if (feature.taskList) {
+    const hasActive = feature.taskList.some(t => t.status === 'in_progress');
+    if (hasActive) pass();
+  }
+
+  // No task in_progress — inject advisory warning
+  approve(
+    `[morph-spec] WARNING: No active task tracking detected during implement phase.\n` +
+    `Before writing code, start a task:\n` +
+    `  npx morph-spec task next ${name}        # see what's next\n` +
+    `  npx morph-spec task start ${name} <id>   # mark it in progress\n` +
+    `Task tracking ensures validators run, checkpoints fire, and progress is recorded.`
+  );
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/claude-code/session-start/inject-morph-context.js

@@ -54,11 +54,11 @@ const SPEC_MAX_CHARS = getSpecMaxChars();
  * @param {string} cwd - Project root path
  */
 function saveStateSync(state, cwd) {
+  const statePath = join(cwd, '.morph/state.json');
+  const tmpPath = `${statePath}.tmp.hook.${process.pid}`;
   try {
     state.metadata = state.metadata || {};
     state.metadata.lastUpdated = new Date().toISOString();
-    const statePath = join(cwd, '.morph/state.json');
-    const tmpPath = `${statePath}.tmp.hook.${process.pid}`;
     writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf8');
     renameSync(tmpPath, statePath);
   } catch {
@@ -209,6 +209,59 @@ try {
     }
   }
 
+  // ── MCP status injection ────────────────────────────────────────────────────
+  // Cross-reference configured MCPs with phase recommendations from mcp-registry.json.
+  // Fail-open: all inside try/catch, no crash on missing files.
+  try {
+    const currentPhase = active ? derivePhaseForFeature(active.name) : '';
+    if (currentPhase) {
+      // Read configured MCPs from settings
+      const configuredMcps = new Set();
+      const settingsFiles = [
+        join(process.cwd(), '.claude', 'settings.local.json'),
+        join(process.cwd(), '.claude', 'settings.json'),
+      ];
+      for (const sf of settingsFiles) {
+        if (existsSync(sf)) {
+          try {
+            const s = JSON.parse(readFileSync(sf, 'utf8'));
+            for (const name of Object.keys(s.mcpServers || {})) {
+              configuredMcps.add(name.toLowerCase());
+            }
+          } catch { /* ignore */ }
+        }
+      }
+
+      // Read recommended MCPs from phases.json or mcp-registry.json
+      let recommended = [];
+      const registryPaths = [
+        join(process.cwd(), 'framework', 'skills', 'level-0-meta', 'mcp-registry.json'),
+        join(process.cwd(), '.morph', 'framework', 'skills', 'level-0-meta', 'mcp-registry.json'),
+      ];
+      for (const rp of registryPaths) {
+        if (existsSync(rp)) {
+          try {
+            const registry = JSON.parse(readFileSync(rp, 'utf8'));
+            recommended = registry.phaseMatrix?.[currentPhase] || [];
+            break;
+          } catch { /* ignore */ }
+        }
+      }
+
+      if (recommended.length > 0) {
+        const mcpStatus = recommended.map(name => {
+          const isConfigured = configuredMcps.has(name.toLowerCase());
+          return `${name} ${isConfigured ? '✓' : '✗ (recommended)'}`;
+        });
+        lines.push('');
+        lines.push(`MCPs: ${mcpStatus.join(', ')}`);
+      }
+    }
+  } catch {
+    // Fail-open — MCP status must never block the session
+  }
+  // ────────────────────────────────────────────────────────────────────────────
+
   // Remind about key commands
   lines.push('');
   lines.push('Key commands: morph-spec status <feature> | morph-spec phase advance <feature> | morph-spec approve <feature> <gate>');

package/framework/hooks/claude-code/session-start/post-compact-restore.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+/**
+ * SessionStart Hook: Post-Compact Context Restore
+ *
+ * Event: SessionStart | Matcher: compact
+ *
+ * Fires ONLY when a session starts after context compaction.
+ * Reads the latest pre-compact memory file and injects the richContext
+ * block (decisions.md snippet + task list) so Claude resumes with full
+ * morph awareness even if the compact summary was truncated.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { injectContext, pass } from '../../shared/hook-response.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { buildRestoreBlock, findLatestMemoryFile } from '../../shared/compact-restore.js';
+
+try {
+  if (!stateExists()) pass();
+
+  const memoryDir = join(process.cwd(), '.morph', 'memory');
+  if (!existsSync(memoryDir)) pass();
+
+  const files = readdirSync(memoryDir);
+  const latest = findLatestMemoryFile(files);
+  if (!latest) pass();
+
+  const raw = readFileSync(join(memoryDir, latest), 'utf-8');
+  const snapshot = JSON.parse(raw);
+
+  const block = buildRestoreBlock(snapshot);
+  if (!block) pass();
+
+  injectContext(block);
+} catch {
+  process.exit(0);
+}

package/framework/hooks/claude-code/stop/validate-completion.js

@@ -21,7 +21,7 @@
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import {
-  stateExists, loadState, getActiveFeature, getMissingOutputs, derivePhaseForFeature,
+  stateExists, getActiveFeature, getMostRecentFeature, getMissingOutputs, derivePhaseForFeature,
 } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
@@ -40,20 +40,7 @@ try {
 
   // getActiveFeature() only returns in_progress/draft features.
   // Fall back to the most recently updated feature when all features are 'done'.
-  let active = getActiveFeature();
-  if (!active) {
-    const state = loadState();
-    if (state?.features) {
-      let latestUpdate = '';
-      for (const [name, feature] of Object.entries(state.features)) {
-        const updated = feature.updatedAt || feature.createdAt || '';
-        if (updated >= latestUpdate) {
-          latestUpdate = updated;
-          active = { name, feature };
-        }
-      }
-    }
-  }
+  let active = getActiveFeature() || getMostRecentFeature();
   if (!active) pass();
 
   const { name, feature } = active;

package/framework/hooks/claude-code/user-prompt/enrich-prompt.js

@@ -15,7 +15,7 @@
  */
 
 import { readStdin } from '../../shared/stdin-reader.js';
-import { stateExists, loadState, getActiveFeature, getFeature, getPendingGates } from '../../shared/state-reader.js';
+import { stateExists, loadState, getActiveFeature, getFeature, getPendingGates, derivePhaseForFeature } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 
@@ -37,7 +37,8 @@ try {
   // Check if a feature name is mentioned
   for (const [featureName, feature] of Object.entries(state.features)) {
     if (promptLower.includes(featureName.toLowerCase())) {
-      context.push(`[morph-spec] Feature '${featureName}': phase=${feature.phase}, status=${feature.status}`);
+      const featurePhase = feature.phase || derivePhaseForFeature(featureName);
+      context.push(`[morph-spec] Feature '${featureName}': phase=${featurePhase}, status=${feature.status}`);
       if (feature.tasks?.total > 0) {
         context.push(`  Tasks: ${feature.tasks.completed || 0}/${feature.tasks.total} completed`);
       }
@@ -50,16 +51,33 @@ try {
   if (active) {
     const { name, feature } = active;
 
+    const activePhase = feature.phase || derivePhaseForFeature(name);
     const codeKeywords = ['implement', 'code', 'start coding', 'write the code', 'build it', 'let\'s build'];
     const wantsToCode = codeKeywords.some(kw => promptLower.includes(kw));
 
-    if (wantsToCode && feature.phase !== 'implement' && feature.phase !== 'sync') {
+    if (wantsToCode && activePhase !== 'implement' && activePhase !== 'sync') {
       context.push(
-        `[morph-spec] WARNING: Feature '${name}' is in '${feature.phase}' phase, not 'implement'.` +
+        `[morph-spec] WARNING: Feature '${name}' is in '${activePhase}' phase, not 'implement'.` +
         ` Complete the current phase first or advance: morph-spec phase advance ${name}`
       );
     }
 
+    // Coding intent during implement phase but no task in_progress
+    if (wantsToCode && activePhase === 'implement') {
+      let hasActiveTask = feature.tasks?.inProgress > 0;
+      if (!hasActiveTask && feature.taskList) {
+        hasActiveTask = feature.taskList.some(t => t.status === 'in_progress');
+      }
+      if (!hasActiveTask) {
+        context.push(
+          `[morph-spec] REMINDER: No task is currently in_progress for '${name}'.` +
+          ` Start a task before coding:\n` +
+          `  npx morph-spec task next ${name}        # see what's next\n` +
+          `  npx morph-spec task start ${name} <id>   # mark it in progress`
+        );
+      }
+    }
+
     // Check for approval intent
     const approvalKeywords = ['approve', 'approved', 'looks good', 'lgtm', 'ship it'];
     const wantsToApprove = approvalKeywords.some(kw => promptLower.includes(kw));
@@ -75,7 +93,7 @@ try {
 
     // Check for "next task" intent
     if (promptLower.includes('next task') || promptLower.includes('what\'s next')) {
-      if (feature.phase === 'implement') {
+      if (activePhase === 'implement') {
         context.push(
           `[morph-spec] Use: morph-spec task next ${name}`
         );

package/framework/hooks/shared/compact-restore.js

@@ -0,0 +1,100 @@
+/**
+ * Shared helpers for post-compact context restoration.
+ *
+ * Used by:
+ *   - pre-compact hook: buildRichContext() to enrich memory file
+ *   - post-compact-restore hook: buildRestoreBlock() + findLatestMemoryFile() to inject context
+ *
+ * Pure functions — no I/O.
+ */
+
+export const DECISIONS_MAX_CHARS = 1500;
+export const MAX_PENDING_TASKS   = 8;
+
+/**
+ * Build the richContext object to embed in pre-compact memory file.
+ * @param {Object} feature          - Feature state object (tasks, taskList)
+ * @param {string} phase            - Current derived phase string
+ * @param {string} decisionsContent - Raw text of decisions.md (may be empty string)
+ * @returns {Object} richContext
+ */
+export function buildRichContext(feature, phase, decisionsContent) {
+  const taskList = Array.isArray(feature.taskList) ? feature.taskList : [];
+
+  const inProgress = taskList
+    .filter(t => t.status === 'in_progress')
+    .map(t => t.id);
+
+  const nextPending = taskList
+    .filter(t => t.status === 'pending')
+    .slice(0, MAX_PENDING_TASKS)
+    .map(t => ({ id: t.id, title: t.title }));
+
+  const decisionsSnippet = decisionsContent.length > DECISIONS_MAX_CHARS
+    ? decisionsContent.slice(0, DECISIONS_MAX_CHARS)
+    : decisionsContent;
+
+  return {
+    phase,
+    tasks:            feature.tasks || {},
+    decisionsSnippet,
+    inProgress,
+    nextPending,
+  };
+}
+
+/**
+ * Build the context block string to inject in session-start after compact.
+ * @param {Object} memorySnapshot - Parsed pre-compact-*.json file contents
+ * @returns {string|null} Block string, or null if no richContext present
+ */
+export function buildRestoreBlock(memorySnapshot) {
+  const rc = memorySnapshot?.richContext;
+  if (!rc) return null;
+
+  const { timestamp, activeFeature } = memorySnapshot;
+  const { phase, tasks, decisionsSnippet, inProgress, nextPending } = rc;
+
+  const done  = tasks?.completed ?? '?';
+  const total = tasks?.total     ?? '?';
+
+  const lines = [
+    `\uD83D\uDD04 POST-COMPACT RESTORE \u2014 context from pre-compact snapshot (${timestamp})`,
+    `Active feature: ${activeFeature} | Phase: ${phase} | Tasks: ${done}/${total}`,
+  ];
+
+  if (decisionsSnippet) {
+    lines.push('');
+    lines.push('Key decisions (at time of compact):');
+    lines.push(decisionsSnippet);
+  }
+
+  if (inProgress.length > 0) {
+    lines.push('');
+    lines.push(`In progress at compact time: [${inProgress.join(', ')}]`);
+  }
+
+  if (nextPending.length > 0) {
+    lines.push('');
+    lines.push('Next pending at compact time:');
+    for (const t of nextPending) {
+      lines.push(`  [${t.id}] ${t.title}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Find the most recent pre-compact memory file from a list of filenames.
+ * Files named pre-compact-{ISO-timestamp-sanitized}.json — sort descending picks latest.
+ * @param {string[]} filenames - Array of filenames in the memory directory
+ * @returns {string|null} Latest filename, or null if none found
+ */
+export function findLatestMemoryFile(filenames) {
+  const matches = filenames
+    .filter(f => f.startsWith('pre-compact-') && f.endsWith('.json'))
+    .sort()
+    .reverse();
+  return matches.length > 0 ? matches[0] : null;
+}