metame-cli 1.4.15 → 1.4.18

package/scripts/skill-evolution.js

@@ -11,7 +11,7 @@
  *   - Writes to evolution_queue.yaml for immediate action
  *
  * COLD PATH (batched, Haiku-powered):
- *   - Piggybacks on distill.js (every 4h or on launch)
+ *   - Runs as standalone heartbeat script task (skill-evolve, default 6h)
  *   - Haiku analyzes accumulated skill signals for nuanced insights
  *   - Merges evolution data into skill's evolution.json + SKILL.md
  *
@@ -35,6 +35,8 @@ const os = require('os');
 const HOME = os.homedir();
 const METAME_DIR = path.join(HOME, '.metame');
 const SKILL_SIGNAL_FILE = path.join(METAME_DIR, 'skill_signals.jsonl');
+const SKILL_SIGNAL_OVERFLOW_FILE = path.join(METAME_DIR, 'skill_signals.overflow.jsonl');
+const SKILL_SIGNAL_LOCK_FILE = path.join(METAME_DIR, 'skill_signals.lock');
 const EVOLUTION_QUEUE_FILE = path.join(METAME_DIR, 'evolution_queue.yaml');
 const EVOLUTION_POLICY_FILE = path.join(METAME_DIR, 'evolution_policy.yaml');
 const BRAIN_FILE = path.join(HOME, '.claude_profile.yaml');
@@ -113,6 +115,54 @@ Respond with ONLY a JSON code block:
 If no actionable insights, respond with exactly: NO_EVOLUTION`,
 };
 
+function clampInt(value, fallback, min, max) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  const i = Math.floor(n);
+  return Math.max(min, Math.min(max, i));
+}
+
+function sanitizePatternList(value, fallback) {
+  const list = Array.isArray(value) ? value : fallback;
+  const clean = [];
+  for (const v of list) {
+    if (typeof v !== 'string') continue;
+    const p = v.trim();
+    if (!p || p.length > 300) continue;
+    try {
+      // Validate regex compileability once so hot path won't crash at runtime.
+      // eslint-disable-next-line no-new
+      new RegExp(p, 'i');
+      clean.push(p);
+    } catch { /* invalid pattern */ }
+  }
+  return clean.length > 0 ? clean : fallback.slice();
+}
+
+function sanitizePolicy(input) {
+  const merged = { ...DEFAULT_POLICY, ...(input && typeof input === 'object' ? input : {}) };
+  const policy = {
+    ...merged,
+    version: clampInt(merged.version, DEFAULT_POLICY.version, 1, 1000000),
+    hot_failure_threshold: clampInt(merged.hot_failure_threshold, DEFAULT_POLICY.hot_failure_threshold, 1, 50),
+    hot_failure_window_minutes: clampInt(merged.hot_failure_window_minutes, DEFAULT_POLICY.hot_failure_window_minutes, 1, 24 * 60),
+    min_signals_for_distill: clampInt(merged.min_signals_for_distill, DEFAULT_POLICY.min_signals_for_distill, 1, 5000),
+    max_signals_buffer: clampInt(merged.max_signals_buffer, DEFAULT_POLICY.max_signals_buffer, 20, 20000),
+    min_evidence_for_update: clampInt(merged.min_evidence_for_update, DEFAULT_POLICY.min_evidence_for_update, 1, 20),
+    min_evidence_for_gap: clampInt(merged.min_evidence_for_gap, DEFAULT_POLICY.min_evidence_for_gap, 1, 20),
+    max_updates_per_analysis: clampInt(merged.max_updates_per_analysis, DEFAULT_POLICY.max_updates_per_analysis, 1, 20),
+    max_gaps_per_analysis: clampInt(merged.max_gaps_per_analysis, DEFAULT_POLICY.max_gaps_per_analysis, 1, 20),
+    self_eval_interval: clampInt(merged.self_eval_interval, DEFAULT_POLICY.self_eval_interval, 1, 1000),
+    cold_path_run_count: clampInt(merged.cold_path_run_count, DEFAULT_POLICY.cold_path_run_count, 0, 1000000),
+    complaint_patterns: sanitizePatternList(merged.complaint_patterns, DEFAULT_POLICY.complaint_patterns),
+    missing_skill_patterns: sanitizePatternList(merged.missing_skill_patterns, DEFAULT_POLICY.missing_skill_patterns),
+    prompt_template: (typeof merged.prompt_template === 'string' && merged.prompt_template.trim())
+      ? merged.prompt_template
+      : DEFAULT_POLICY.prompt_template,
+  };
+  return policy;
+}
+
 function loadPolicy() {
   let yaml;
   try { yaml = require('js-yaml'); } catch { return { ...DEFAULT_POLICY }; }
@@ -125,8 +175,7 @@ function loadPolicy() {
     }
     const content = fs.readFileSync(EVOLUTION_POLICY_FILE, 'utf8');
     const loaded = yaml.load(content) || {};
-    // Merge with defaults (new fields auto-added on upgrade)
-    return { ...DEFAULT_POLICY, ...loaded };
+    return sanitizePolicy(loaded);
   } catch {
     return { ...DEFAULT_POLICY };
   }
@@ -135,7 +184,7 @@ function loadPolicy() {
 function savePolicy(yaml, policy) {
   try {
     if (!fs.existsSync(METAME_DIR)) fs.mkdirSync(METAME_DIR, { mode: 0o700, recursive: true });
-    fs.writeFileSync(EVOLUTION_POLICY_FILE, yaml.dump(policy, { lineWidth: 120 }), 'utf8');
+    fs.writeFileSync(EVOLUTION_POLICY_FILE, yaml.dump(sanitizePolicy(policy), { lineWidth: 120 }), 'utf8');
   } catch {}
 }
 
@@ -174,7 +223,8 @@ function extractSkillSignal(prompt, output, error, files, cwd, toolUsageLog) {
 
   const hasSkills = skills.length > 0;
   const hasError = !!error;
-  const hasToolFailure = output && /(?:failed|error|not found|not available|skill.{0,20}(?:missing|absent|not.{0,10}install))/i.test(output);
+  const outputText = typeof output === 'string' ? output : '';
+  const hasToolFailure = /(?:failed|error|not found|not available|skill.{0,20}(?:missing|absent|not.{0,10}install))/i.test(outputText);
 
   // Skip if no skill involvement and no failure
   if (!hasSkills && !hasError && !hasToolFailure) return null;
@@ -185,30 +235,103 @@ function extractSkillSignal(prompt, output, error, files, cwd, toolUsageLog) {
     skills_invoked: skills,
     tools_used: tools.slice(0, 20), // cap for storage
     error: error ? error.substring(0, 500) : null,
+    output_excerpt: outputText.substring(0, 500),
     has_tool_failure: !!hasToolFailure,
     files_modified: (files || []).slice(0, 10),
     cwd: cwd || null,
-    outcome: error ? 'error' : (output ? 'success' : 'empty'),
+    outcome: (hasError || hasToolFailure) ? 'error' : (outputText ? 'success' : 'empty'),
   };
 }
 
 /**
  * Append a skill signal to the JSONL buffer.
  */
+function withSkillSignalLock(fn) {
+  if (!fs.existsSync(METAME_DIR)) fs.mkdirSync(METAME_DIR, { mode: 0o700, recursive: true });
+  const maxRetry = 80;
+  const retryMs = 8;
+  const staleMs = 30 * 1000;
+
+  let acquired = false;
+  for (let i = 0; i < maxRetry; i++) {
+    try {
+      const fd = fs.openSync(SKILL_SIGNAL_LOCK_FILE, 'wx');
+      fs.writeSync(fd, String(process.pid));
+      fs.closeSync(fd);
+      acquired = true;
+      break;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      try {
+        const age = Date.now() - fs.statSync(SKILL_SIGNAL_LOCK_FILE).mtimeMs;
+        if (age > staleMs) {
+          fs.unlinkSync(SKILL_SIGNAL_LOCK_FILE);
+          continue;
+        }
+      } catch { /* lock released elsewhere */ }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, retryMs);
+    }
+  }
+
+  if (!acquired) return false;
+  try {
+    fn();
+    return true;
+  } finally {
+    try { fs.unlinkSync(SKILL_SIGNAL_LOCK_FILE); } catch {}
+  }
+}
+
+function writeSkillSignalLines(lines) {
+  const tmp = SKILL_SIGNAL_FILE + `.tmp.${process.pid}`;
+  const content = Array.isArray(lines) && lines.length > 0 ? lines.join('\n') + '\n' : '';
+  fs.writeFileSync(tmp, content, 'utf8');
+  fs.renameSync(tmp, SKILL_SIGNAL_FILE);
+}
+
 function appendSkillSignal(signal) {
   if (!signal) return;
   try {
-    if (!fs.existsSync(METAME_DIR)) fs.mkdirSync(METAME_DIR, { mode: 0o700, recursive: true });
+    const payload = JSON.stringify(signal);
+    const policy = loadPolicy();
 
-    // Append
-    fs.appendFileSync(SKILL_SIGNAL_FILE, JSON.stringify(signal) + '\n', 'utf8');
+    const locked = withSkillSignalLock(() => {
+      let lines = [];
+      try {
+        lines = fs.readFileSync(SKILL_SIGNAL_FILE, 'utf8').split('\n').filter(Boolean);
+      } catch { /* first write */ }
+
+      // Drain overflow written during prior lock-contention periods.
+      // unlink AFTER writeSkillSignalLines succeeds — crash-safe ordering.
+      let overflowDrained = false;
+      try {
+        const overflowLines = fs.readFileSync(SKILL_SIGNAL_OVERFLOW_FILE, 'utf8').split('\n').filter(Boolean);
+        if (overflowLines.length > 0) {
+          lines = lines.concat(overflowLines);
+          overflowDrained = true;
+        }
+      } catch { /* no overflow file — normal case */ }
+
+      lines.push(payload);
+      if (lines.length > policy.max_signals_buffer) {
+        lines = lines.slice(-policy.max_signals_buffer);
+      }
+      writeSkillSignalLines(lines);
+      // Unlink overflow only after main file is safely written.
+      if (overflowDrained) {
+        try { fs.unlinkSync(SKILL_SIGNAL_OVERFLOW_FILE); } catch { /* already gone */ }
+      }
+    });
 
-    // Truncate if over limit (keep newest)
-    const content = fs.readFileSync(SKILL_SIGNAL_FILE, 'utf8').trim();
-    const lines = content.split('\n');
-    const policy = loadPolicy();
-    if (lines.length > policy.max_signals_buffer) {
-      fs.writeFileSync(SKILL_SIGNAL_FILE, lines.slice(-policy.max_signals_buffer).join('\n') + '\n', 'utf8');
+    if (!locked) {
+      // Last-resort fallback: write to overflow side-file so the next lock-holder
+      // can drain and apply max_signals_buffer cap — never bypassing buffer rules.
+      // Guard against unbounded growth: drop entry if overflow already at cap.
+      try {
+        const ofLines = fs.readFileSync(SKILL_SIGNAL_OVERFLOW_FILE, 'utf8').split('\n').filter(Boolean);
+        if (ofLines.length >= policy.max_signals_buffer) return;
+      } catch { /* overflow file doesn't exist yet */ }
+      fs.appendFileSync(SKILL_SIGNAL_OVERFLOW_FILE, payload + '\n', 'utf8');
     }
   } catch {
     // Non-fatal
@@ -261,7 +384,12 @@ function checkHotEvolution(signal) {
   }
 
   // Rule 2: User complaints about a skill
-  const complaintRe = new RegExp(policy.complaint_patterns.join('|'), 'i');
+  let complaintRe;
+  try {
+    complaintRe = new RegExp(policy.complaint_patterns.join('|'), 'i');
+  } catch {
+    complaintRe = new RegExp(DEFAULT_POLICY.complaint_patterns.join('|'), 'i');
+  }
   if (signal.prompt && complaintRe.test(signal.prompt) && signal.skills_invoked.length > 0) {
     for (const sk of signal.skills_invoked) {
       addToQueue(queue, {
@@ -274,8 +402,18 @@ function checkHotEvolution(signal) {
   }
 
   // Rule 3: Missing skill detection
-  const missingRe = new RegExp(policy.missing_skill_patterns.join('|'), 'i');
-  if (signal.outcome !== 'success' && signal.prompt && missingRe.test((signal.error || '') + (signal.prompt || ''))) {
+  let missingRe;
+  try {
+    missingRe = new RegExp(policy.missing_skill_patterns.join('|'), 'i');
+  } catch {
+    missingRe = new RegExp(DEFAULT_POLICY.missing_skill_patterns.join('|'), 'i');
+  }
+  const missText = [(signal.error || ''), (signal.prompt || ''), (signal.output_excerpt || '')].join('\n');
+  const hasMissingPattern = missingRe.test(missText);
+  const hasExplicitSkillMiss = signal.has_tool_failure &&
+    /skill|技能|能力/i.test(missText) &&
+    /not found|missing|absent|no skill|找不到|没有找到|能力不足/i.test(missText);
+  if (signal.prompt && (hasMissingPattern || hasExplicitSkillMiss)) {
     addToQueue(queue, {
       type: 'skill_gap',
       skill_name: null,
@@ -295,7 +433,7 @@ function checkHotEvolution(signal) {
     if (isSuccess || isFail) {
       for (const sk of signal.skills_invoked) {
         const skillDir = findSkillDir(sk);
-        if (skillDir) trackInsightOutcome(skillDir, isSuccess);
+        if (skillDir) trackInsightOutcome(skillDir, isSuccess, signal);
       }
     }
   }
@@ -305,7 +443,51 @@ function checkHotEvolution(signal) {
  * Update insight outcome stats in evolution.json for a skill.
  * Tracks success_count, fail_count, last_applied_at per insight text.
  */
-function trackInsightOutcome(skillDir, isSuccess) {
+const INSIGHT_STOPWORDS = new Set([
+  'the', 'and', 'for', 'with', 'that', 'this', 'from', 'into', 'when', 'where',
+  'user', 'skill', 'meta', 'metame', 'should', 'always', 'never', 'please',
+  '问题', '用户', '技能', '需要', '应该', '这个', '那个', '以及', '如果', '然后',
+]);
+
+function extractInsightTokens(text) {
+  const raw = String(text || '').toLowerCase();
+  const en = raw.match(/[a-z][a-z0-9_.-]{2,}/g) || [];
+  const zh = raw.match(/[\u4e00-\u9fff]{2,}/g) || [];
+  const tokens = [...en, ...zh]
+    .map(t => t.trim())
+    .filter(t => t.length >= 2 && !INSIGHT_STOPWORDS.has(t));
+  return [...new Set(tokens)];
+}
+
+function pickMatchedInsights(allInsights, signal) {
+  if (!signal || !Array.isArray(allInsights) || allInsights.length === 0) return [];
+
+  const context = [
+    signal.prompt || '',
+    signal.error || '',
+    signal.output_excerpt || '',
+    ...(Array.isArray(signal.tools_used) ? signal.tools_used.map(t => `${t.name || ''} ${t.context || ''}`) : []),
+    ...(Array.isArray(signal.files_modified) ? signal.files_modified : []),
+  ].join('\n').toLowerCase();
+
+  const scored = allInsights
+    .map((insight) => {
+      const tokens = extractInsightTokens(insight).slice(0, 12);
+      if (tokens.length === 0) return { insight, score: 0 };
+      let score = 0;
+      for (const token of tokens) {
+        if (context.includes(token)) score++;
+      }
+      return { insight, score };
+    })
+    .filter(x => x.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  if (scored.length > 0) return scored.slice(0, 3).map(x => x.insight);
+  return allInsights.length === 1 ? [allInsights[0]] : [];
+}
+
+function trackInsightOutcome(skillDir, isSuccess, signal = null) {
   const evoPath = path.join(skillDir, 'evolution.json');
   let data = {};
   try { data = JSON.parse(fs.readFileSync(evoPath, 'utf8')); } catch { return; }
@@ -317,8 +499,9 @@ function trackInsightOutcome(skillDir, isSuccess) {
     ...(data.fixes || []),
     ...(data.contexts || []),
   ];
+  const targetInsights = signal ? pickMatchedInsights(allInsights, signal) : allInsights;
 
-  for (const insight of allInsights) {
+  for (const insight of targetInsights) {
     if (!data.insights_stats[insight]) {
       data.insights_stats[insight] = { success_count: 0, fail_count: 0, last_applied_at: null };
     }
@@ -333,7 +516,7 @@ function trackInsightOutcome(skillDir, isSuccess) {
 
 // ─────────────────────────────────────────────
 // Cold Path: Haiku-Powered Analysis
-// (called from distill.js)
+// (called by heartbeat script task: skill-evolve)
 // ─────────────────────────────────────────────
 
 /**
@@ -362,7 +545,6 @@ async function distillSkills() {
   // Get installed skills list
   const installedSkills = listInstalledSkills();
   if (installedSkills.length === 0) {
-    clearSignals();
     return null;
   }
 
@@ -414,7 +596,6 @@ async function distillSkills() {
 
     const jsonMatch = result.match(/```json\s*([\s\S]*?)```/);
     if (!jsonMatch) {
-      clearSignals();
       return null;
     }
 
@@ -572,8 +753,15 @@ RULES:
     const patchData = yaml.load(yamlMatch[1]);
     if (!patchData || typeof patchData !== 'object') return;
 
-    // Apply patch (merge, don't overwrite entirely)
-    const newPolicy = { ...policy, ...patchData };
+    // Apply patch with schema/type sanitization.
+    const newPolicy = sanitizePolicy({ ...policy, ...patchData });
+    if (newPolicy.version <= policy.version) {
+      newPolicy.version = policy.version + 1;
+    }
+    if (JSON.stringify(newPolicy) === JSON.stringify(policy)) {
+      console.log('🧬 Policy self-eval: patch produced no effective change.');
+      return;
+    }
     savePolicy(yaml, newPolicy);
     console.log(`🧬 Policy self-evolved: v${policy.version} → v${newPolicy.version}`);
 
@@ -591,7 +779,16 @@ function loadEvolutionQueue(yaml) {
     if (!fs.existsSync(EVOLUTION_QUEUE_FILE)) return { items: [] };
     const content = fs.readFileSync(EVOLUTION_QUEUE_FILE, 'utf8');
     const data = yaml.load(content);
-    return data && Array.isArray(data.items) ? data : { items: [] };
+    const queue = data && Array.isArray(data.items) ? data : { items: [] };
+    let changed = false;
+    for (const item of queue.items) {
+      if (!item.id) {
+        item.id = `q-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+        changed = true;
+      }
+    }
+    if (changed) saveEvolutionQueue(yaml, queue);
+    return queue;
   } catch {
     return { items: [] };
   }
@@ -604,18 +801,24 @@ function saveEvolutionQueue(yaml, queue) {
 }
 
 function addToQueue(queue, entry) {
-  // Dedup by type + skill_name (update existing instead of adding duplicate)
+  // Dedup pending entries by core key. Skill gaps also include search_hint so unrelated gaps don't collapse.
   const existing = queue.items.find(i =>
-    i.type === entry.type && i.skill_name === entry.skill_name && i.status === 'pending'
+    i.type === entry.type &&
+    i.skill_name === entry.skill_name &&
+    i.status === 'pending' &&
+    (entry.type !== 'skill_gap' || (i.search_hint || '') === (entry.search_hint || ''))
   );
 
   if (existing) {
     existing.evidence_count = (existing.evidence_count || 0) + (entry.evidence_count || 1);
     existing.last_seen = new Date().toISOString();
+    if (entry.reason) existing.reason = entry.reason;
+    if (entry.search_hint) existing.search_hint = entry.search_hint;
     return;
   }
 
   queue.items.push({
+    id: `q-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`,
     ...entry,
     detected: new Date().toISOString(),
     last_seen: new Date().toISOString(),
@@ -639,13 +842,11 @@ function checkEvolutionQueue() {
 
   const queue = loadEvolutionQueue(yaml);
   const pendingItems = queue.items.filter(i => i.status === 'pending');
-  if (pendingItems.length === 0) return [];
-
   const notifications = [];
+  const policy = loadPolicy();
 
   for (const item of pendingItems) {
     // Require minimum evidence before notifying
-    const policy = loadPolicy();
     const minEvidence = item.type === 'skill_gap' ? policy.min_evidence_for_gap : policy.min_evidence_for_update;
     if ((item.evidence_count || 1) < minEvidence) continue;
 
@@ -655,13 +856,14 @@ function checkEvolutionQueue() {
   }
 
   // Prune old resolved items (> 30 days)
+  const beforeLen = queue.items.length;
   const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000;
   queue.items = queue.items.filter(i =>
     i.status === 'pending' || i.status === 'notified' ||
     (new Date(i.last_seen || i.detected).getTime() > cutoff)
   );
 
-  if (notifications.length > 0) {
+  if (notifications.length > 0 || queue.items.length !== beforeLen) {
     saveEvolutionQueue(yaml, queue);
   }
 
@@ -687,6 +889,42 @@ function resolveQueueItem(type, skillName, resolution) {
   }
 }
 
+/**
+ * Mark queue item resolved by queue id.
+ * Returns true when updated.
+ */
+function resolveQueueItemById(id, resolution) {
+  let yaml;
+  try { yaml = require('js-yaml'); } catch { return false; }
+  if (!id) return false;
+
+  const queue = loadEvolutionQueue(yaml);
+  const item = queue.items.find(i =>
+    i.id === id && (i.status === 'pending' || i.status === 'notified')
+  );
+  if (!item) return false;
+
+  item.status = resolution; // 'installed' | 'dismissed'
+  item.resolved_at = new Date().toISOString();
+  saveEvolutionQueue(yaml, queue);
+  return true;
+}
+
+/**
+ * List queue items for manual triage.
+ */
+function listQueueItems({ status = null, limit = 20 } = {}) {
+  let yaml;
+  try { yaml = require('js-yaml'); } catch { return []; }
+  const queue = loadEvolutionQueue(yaml);
+  const items = Array.isArray(queue.items) ? queue.items : [];
+  const filtered = status ? items.filter(i => i.status === status) : items;
+  return filtered
+    .slice()
+    .sort((a, b) => new Date(b.last_seen || b.detected || 0).getTime() - new Date(a.last_seen || a.detected || 0).getTime())
+    .slice(0, Math.max(1, limit));
+}
+
 // ─────────────────────────────────────────────
 // Evolution.json Merge (JS port of merge_evolution.py)
 // ─────────────────────────────────────────────
@@ -726,8 +964,11 @@ function smartStitch(skillDir) {
   try { data = JSON.parse(fs.readFileSync(evoPath, 'utf8')); } catch { return; }
 
   // Build evolution section
+  const AUTO_START = '<!-- METAME-EVOLUTION:START -->';
+  const AUTO_END = '<!-- METAME-EVOLUTION:END -->';
   const sections = [];
-  sections.push('\n\n## User-Learned Best Practices & Constraints');
+  sections.push(`\n\n${AUTO_START}`);
+  sections.push('\n## User-Learned Best Practices & Constraints');
   sections.push('\n> **Auto-Generated Section**: Maintained by skill-evolution-manager. Do not edit manually.');
 
   // Helper: get quality indicator for an insight based on stats
@@ -755,13 +996,17 @@ function smartStitch(skillDir) {
     sections.push(`\n${data.custom_prompts}`);
   }
 
+  sections.push(`\n${AUTO_END}\n`);
   const evolutionBlock = sections.join('\n');
 
   let content = fs.readFileSync(skillMdPath, 'utf8');
-  const pattern = /(\n+## User-Learned Best Practices & Constraints[\s\S]*$)/;
+  const markerPattern = new RegExp(`${AUTO_START}[\\s\\S]*?${AUTO_END}\\n?`);
+  const legacyPattern = /\n+## User-Learned Best Practices & Constraints[\s\S]*?(?=\n##\s+|\n#\s+|$)/;
 
-  if (pattern.test(content)) {
-    content = content.replace(pattern, evolutionBlock);
+  if (markerPattern.test(content)) {
+    content = content.replace(markerPattern, evolutionBlock.trimStart());
+  } else if (legacyPattern.test(content)) {
+    content = content.replace(legacyPattern, evolutionBlock);
   } else {
     content = content + evolutionBlock;
   }
@@ -787,7 +1032,10 @@ function readRecentSignals() {
 }
 
 function clearSignals() {
-  try { fs.writeFileSync(SKILL_SIGNAL_FILE, '', 'utf8'); } catch {}
+  try {
+    const locked = withSkillSignalLock(() => writeSkillSignalLines([]));
+    if (!locked) fs.writeFileSync(SKILL_SIGNAL_FILE, '', 'utf8');
+  } catch {}
 }
 
 function listInstalledSkills() {
@@ -827,6 +1075,8 @@ module.exports = {
   distillSkills,
   checkEvolutionQueue,
   resolveQueueItem,
+  resolveQueueItemById,
+  listQueueItems,
   mergeEvolution,
   smartStitch,
   trackInsightOutcome,

package/scripts/skill-evolution.test.js

@@ -0,0 +1,107 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const yaml = require('js-yaml');
+
+const ROOT = path.resolve(__dirname, '..');
+
+function mkHome() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'metame-skill-evo-'));
+}
+
+function runWithHome(home, code) {
+  return execFileSync(process.execPath, ['-e', code], {
+    cwd: ROOT,
+    env: { ...process.env, HOME: home },
+    encoding: 'utf8',
+  });
+}
+
+test('captures missing-skill failures into skill_gap queue', () => {
+  const home = mkHome();
+  runWithHome(home, `
+    const se = require('./scripts/skill-evolution');
+    const s = se.extractSkillSignal('帮我做封面图', 'Error: skill not found: nano-banana', null, [], process.cwd(), []);
+    se.appendSkillSignal(s);
+    se.checkHotEvolution(s);
+  `);
+
+  const queuePath = path.join(home, '.metame', 'evolution_queue.yaml');
+  const queue = yaml.load(fs.readFileSync(queuePath, 'utf8'));
+  assert.equal(Array.isArray(queue.items), true);
+  assert.equal(queue.items.length, 1);
+  assert.equal(queue.items[0].type, 'skill_gap');
+  assert.equal(queue.items[0].status, 'pending');
+  assert.ok(queue.items[0].id);
+});
+
+test('resolves queue item by id', () => {
+  const home = mkHome();
+  runWithHome(home, `
+    const se = require('./scripts/skill-evolution');
+    const s = se.extractSkillSignal('帮我做封面图', 'Error: skill not found: nano-banana', null, [], process.cwd(), []);
+    se.appendSkillSignal(s);
+    se.checkHotEvolution(s);
+    const items = se.listQueueItems({ status: 'pending', limit: 5 });
+    if (!items[0]) throw new Error('no pending queue item');
+    const ok = se.resolveQueueItemById(items[0].id, 'installed');
+    if (!ok) throw new Error('resolveQueueItemById returned false');
+  `);
+
+  const queuePath = path.join(home, '.metame', 'evolution_queue.yaml');
+  const queue = yaml.load(fs.readFileSync(queuePath, 'utf8'));
+  assert.equal(queue.items.length, 1);
+  assert.equal(queue.items[0].status, 'installed');
+});
+
+test('smartStitch preserves sections after evolution block', () => {
+  const home = mkHome();
+  runWithHome(home, `
+    const fs = require('fs');
+    const path = require('path');
+    const se = require('./scripts/skill-evolution');
+    const dir = path.join(process.env.HOME, 'sample-skill');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'SKILL.md'), '# Demo\\n\\nBody\\n\\n## User-Learned Best Practices & Constraints\\nOld\\n\\n## KeepMe\\nKeep this section\\n');
+    fs.writeFileSync(path.join(dir, 'evolution.json'), JSON.stringify({ preferences: ['prefer concise output'] }, null, 2));
+    se.smartStitch(dir);
+  `);
+
+  const content = fs.readFileSync(path.join(home, 'sample-skill', 'SKILL.md'), 'utf8');
+  assert.match(content, /METAME-EVOLUTION:START/);
+  assert.match(content, /prefer concise output/);
+  assert.match(content, /## KeepMe/);
+  assert.match(content, /Keep this section/);
+});
+
+test('trackInsightOutcome updates only matched insights', () => {
+  const home = mkHome();
+  runWithHome(home, `
+    const fs = require('fs');
+    const path = require('path');
+    const se = require('./scripts/skill-evolution');
+    const dir = path.join(process.env.HOME, '.claude', 'skills', 'demo-skill');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'SKILL.md'), '# Demo');
+    fs.writeFileSync(path.join(dir, 'evolution.json'), JSON.stringify({
+      preferences: ['alpha_mode'],
+      fixes: ['beta_mode']
+    }, null, 2));
+    se.trackInsightOutcome(dir, true, {
+      prompt: 'please use alpha_mode',
+      error: '',
+      output_excerpt: '',
+      tools_used: [],
+      files_modified: []
+    });
+  `);
+
+  const evo = JSON.parse(fs.readFileSync(path.join(home, '.claude', 'skills', 'demo-skill', 'evolution.json'), 'utf8'));
+  assert.equal(typeof evo.insights_stats, 'object');
+  assert.ok(evo.insights_stats.alpha_mode);
+  assert.equal(evo.insights_stats.alpha_mode.success_count, 1);
+  assert.equal(evo.insights_stats.beta_mode, undefined);
+});