harness-everything 0.2.1 → 0.3.6

package/self-evolve/references/memory-resolution.md

@@ -0,0 +1,58 @@
+# Self-Evolve — Memory Resolution & Execution Details
+
+Details moved from SKILL.md. Read when you need the full decision matrix or the reasoning behind the cleanliness rules.
+
+## Responsibility Boundary
+
+The host agent owns access to the current session and any history explicitly exposed by the host. It selects authorized evidence and states a generalized root cause before invoking this skill. `self-evolve` classifies, deduplicates, validates, and persists that result. It MUST NOT scan global transcript stores, persist raw transcripts, or act as a transcript daemon.
+
+## Triggers
+
+- **Post-Circuit Breaker**: Following successful recovery after a `zoom-out` reflection.
+- **Major Breakthrough**: Upon completing complex tasks that revealed non-obvious framework limits or architectural edge cases.
+- **Explicit Request**: When the user asks to "remember this lesson" or "save this to memory".
+
+## Execution Process & Memory Resolution Flow
+
+```mermaid
+flowchart TD
+    Start[Self-Evolve Triggered: Extract Lessons] --> CheckProjectMemory{1. Detect Workspace Memory Architecture?<br>e.g. MEMORY.md, RULES.md}
+    
+    CheckProjectMemory -- Found MEMORY.md / RULES.md --> TargetFile[Set Target Memory File]
+    CheckProjectMemory -- Not Found --> CheckScript{2. Node.js & Script Executable?}
+    
+    CheckScript -- Yes --> RunScript[Execute scripts/persist-memory.js / register-dynamic-skill.js]
+    CheckScript -- No --> PathPlatform[Create Platform State Memory<br>e.g. .github/harness-everything/memories/RULES.md] --> TargetFile
+    
+    RunScript --> Done[Memory Persisted]
+    TargetFile --> CheckLineCount{3. Check Target File Line Count}
+    
+    CheckLineCount -- < 60 Lines --> DirectAppend[Directly Append Rule to Target Memory File]
+    CheckLineCount -- ≥ 60 Lines --> ModularSplit[Categorize & Create Sub-memory File<br>e.g. memories/rules/topic.md]
+    
+    ModularSplit --> LazyLoadIndex[Add 1-Line Index Pointer to Primary MEMORY.md<br>Enable Lazy Loading]
+    
+    DirectAppend --> Done
+    LazyLoadIndex --> Done
+```
+
+For a simple rule, persist only the generalized constraint or tip. For a reusable multi-step procedure, load `skill-creator/SKILL.md`, create the draft skill, and use `register-dynamic-skill.js` to update each platform's `manifest.json` `generated[]` registry. The host agent remains responsible for deciding which evidence is relevant; these scripts do not discover session history.
+
+## Memory Resolution & Cleanliness Rules
+
+1. **Workspace Memory Inspection First**:
+   Before creating new memory files or running scripts, check if the workspace already maintains a primary memory file (such as `MEMORY.md`, `memories/repo/RULES.md`, `CLAUDE.md`, or `AGENTS.md`). If found, prioritize updating the existing structure.
+
+2. **The 60-Line Cleanliness & Lazy Loading Rule**:
+   To prevent Context Bloat and keep workspace memory organized:
+   - **Under 60 Lines**: Append the concise, generalized defensive rule directly to the primary memory file.
+   - **60 Lines or Greater**:
+     - **Modular Split**: Extract the rule into a dedicated topic file under a sub-folder (e.g. `memories/rules/db-migration.md` or `.github/harness-everything/memories/rules/<topic>.md`).
+     - **Index Pointer & Lazy Loading**: Add a single-line link/pointer in the primary `MEMORY.md` (e.g. `- [DB Migration Rules](memories/rules/db-migration.md)`). Future agent sessions will lazy-load the sub-memory file only when touching that specific domain.
+
+3. **Script Tooling Fallback**:
+   If Node.js and `persist-memory.js` are executable, run `node "<this-skill-dir>/scripts/persist-memory.js" "<rule>"`. If script execution fails or is unavailable, use the agent's file tools or memory API directly.
+
+## Purpose
+
+Through `self-evolve`, we transform "invalid trial-and-error", which might otherwise waste Tokens, into a valuable "moat" for the system. Even if the underlying model doesn't become inherently smarter, equipped with these memories, the system will automatically avoid known traps and break through its original reasoning ceiling.

package/self-evolve/scripts/persist-memory.js

@@ -1,40 +1,139 @@
-#!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-
-const args = process.argv.slice(2);
-const memoryText = args[0];
-
-if (!memoryText) {
-  console.error("Usage: node persist-memory.js \"<insight to remember>\"");
-  process.exit(1);
-}
-
-function getWorkspaceRoot() {
-  let dir = path.resolve(process.cwd());
-  while (dir !== path.parse(dir).root) {
-    if (fs.existsSync(path.join(dir, '.git'))) return dir;
-    dir = path.dirname(dir);
-  }
-  return process.cwd();
-}
-
-// Ensure the memory is written to the project root's /memories/repo/ directory
-const currentDir = getWorkspaceRoot();
-const memoryDir = path.join(currentDir, 'memories', 'repo');
-const rulesFile = path.join(memoryDir, 'RULES.md');
-
-try {
-  if (!fs.existsSync(memoryDir)) {
-    fs.mkdirSync(memoryDir, { recursive: true });
-  }
-
-  const timestamp = new Date().toISOString().split('T')[0];
-  const formattedMemory = `\n## [${timestamp}] Self-Evolution Insight\n- ${memoryText}\n`;
-
-  fs.appendFileSync(rulesFile, formattedMemory, 'utf8');
-  console.log(`[Success] Memory persisted to ${rulesFile}`);
-} catch (err) {
-  console.error(`[Error] Failed to write memory: ${err.message}`);
-  process.exit(1);
-}
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const memoryText = args[0];
+
+if (memoryText === '--help' || memoryText === '-h') {
+  console.log(`Append a short defensive rule to memories/repo/RULES.md.
+
+Usage: node persist-memory.js "<insight to remember>"
+
+One positional argument - the extracted root cause / rule, written as a universal,
+high-level statement (not a specific file, line number, or variable name). Wrap it
+in quotes if it contains spaces. Appended under a dated heading; never overwrites
+earlier entries.
+
+Quality gates:
+- Minimum score of 5/10 required for persistence
+- Deduplication check against existing rules
+- Specificity and actionability scoring`);
+  process.exit(0);
+}
+
+if (!memoryText) {
+  console.error("Usage: node persist-memory.js \"<insight to remember>\"");
+  process.exit(1);
+}
+
+// Rule quality scoring system
+function scoreRuleQuality(ruleText, existingRules = []) {
+  let score = 0;
+  
+  // Specificity: mentions specific files, errors, or patterns
+  if (/\.\w{2,4}/.test(ruleText)) score += 2; // File extensions
+  if (/Error|Exception|Warning|錯誤|異常|警告/.test(ruleText)) score += 2; // Error patterns
+  if (/\b(test|lint|build|verify|check|測試|檢查)\b/i.test(ruleText)) score += 1; // Verification terms
+  
+  // Actionability: starts with verb, has clear instruction
+  if (/^(Always|Never|Check|Verify|Prefer|Avoid|Use|不要|總是|檢查|驗證|避免|使用)/i.test(ruleText)) score += 3;
+  if (/^(should|must|will|needs? to|ought|應該|必須|需要)/i.test(ruleText)) score += 2;
+  
+  // Uniqueness: not already in RULES.md
+  const isDuplicate = existingRules.some(existing => {
+    const similarity = calculateSimilarity(ruleText, existing);
+    return similarity > 0.7; // 70% similarity threshold
+  });
+  if (!isDuplicate) score += 3;
+  
+  // Length appropriateness (not too short, not too long)
+  if (ruleText.length > 20 && ruleText.length < 200) score += 1;
+  
+  return Math.min(score, 10); // Cap at 10
+}
+
+// Simple text similarity calculation
+function calculateSimilarity(text1, text2) {
+  const words1 = text1.toLowerCase().split(/\s+/);
+  const words2 = text2.toLowerCase().split(/\s+/);
+  
+  const set1 = new Set(words1);
+  const set2 = new Set(words2);
+  
+  let intersection = 0;
+  for (const word of set1) {
+    if (set2.has(word)) intersection++;
+  }
+  
+  const union = set1.size + set2.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+// Extract existing rules from RULES.md
+function extractExistingRules(rulesFile) {
+  if (!fs.existsSync(rulesFile)) return [];
+  
+  try {
+    const content = fs.readFileSync(rulesFile, 'utf8');
+    const ruleMatches = content.match(/^- .+$/gm) || [];
+    return ruleMatches.map(rule => rule.substring(2)); // Remove "- " prefix
+  } catch (err) {
+    return [];
+  }
+}
+
+function getWorkspaceRoot() {
+  let dir = path.resolve(process.cwd());
+  while (dir !== path.parse(dir).root) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+// Ensure the memory is written to the project root's memories/repo/ directory
+const currentDir = getWorkspaceRoot();
+const memoryDir = path.join(currentDir, 'memories', 'repo');
+const rulesFile = path.join(memoryDir, 'RULES.md');
+
+try {
+  if (!fs.existsSync(memoryDir)) {
+    fs.mkdirSync(memoryDir, { recursive: true });
+  }
+
+  // Extract existing rules for deduplication check
+  const existingRules = extractExistingRules(rulesFile);
+  
+  // Score the rule quality
+  const qualityScore = scoreRuleQuality(memoryText, existingRules);
+  
+  if (qualityScore < 5) {
+    console.error(`[Quality Gate] Rule rejected - score ${qualityScore}/10 (minimum 5 required)`);
+    console.error(`Suggestions to improve:`);
+    console.error(`- Be more specific (mention file types, error patterns)`);
+    console.error(`- Start with action verbs (Always, Never, Check, Verify)`);
+    console.error(`- Ensure the rule is actionable and not already captured`);
+    process.exit(1);
+  }
+  
+  // Check for duplicates
+  const isDuplicate = existingRules.some(existing => {
+    const similarity = calculateSimilarity(memoryText, existing);
+    return similarity > 0.7;
+  });
+  
+  if (isDuplicate) {
+    console.error(`[Quality Gate] Rule rejected - similar rule already exists`);
+    process.exit(1);
+  }
+
+  const timestamp = new Date().toISOString().split('T')[0];
+  const formattedMemory = `\n## [${timestamp}] Self-Evolution Insight (Quality: ${qualityScore}/10)\n- ${memoryText}\n`;
+
+  fs.appendFileSync(rulesFile, formattedMemory, 'utf8');
+  console.log(`[Success] Memory persisted to ${rulesFile} (Quality: ${qualityScore}/10)`);
+} catch (err) {
+  console.error(`[Error] Failed to write memory: ${err.message}`);
+  process.exit(1);
+}

package/self-evolve/scripts/register-dynamic-skill.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+function getWorkspaceRoot() {
+  let dir = path.resolve(process.cwd());
+  while (dir !== path.parse(dir).root) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+function loadManifestHelper() {
+  const candidates = [
+    path.join(__dirname, '../../scripts/lib/manifest'),
+    path.join(__dirname, '../scripts/lib/manifest'),
+    path.join(__dirname, '../../../scripts/lib/manifest'),
+    path.join(getWorkspaceRoot(), 'scripts/lib/manifest'),
+    path.join(getWorkspaceRoot(), 'harness-everything/scripts/lib/manifest'),
+  ];
+  for (const cand of candidates) {
+    try {
+      if (fs.existsSync(cand + '.js') || fs.existsSync(cand)) {
+        return require(cand);
+      }
+    } catch (e) {}
+  }
+  throw new Error('[register-dynamic-skill] Failed to locate manifest helper module (scripts/lib/manifest)');
+}
+
+const { getManifestPath, readManifest, writeManifest, recordGeneratedSkill } = loadManifestHelper();
+
+// Find user home folder
+const userHome = process.env.HOME || process.env.USERPROFILE || '';
+const workspaceRoot = getWorkspaceRoot();
+
+// List of all possible manifest.json home paths
+const manifestHomes = [
+  path.join(workspaceRoot, '.claude'),
+  path.join(workspaceRoot, '.cursor'),
+  path.join(workspaceRoot, '.github'),
+  path.join(workspaceRoot, '.codex'),
+  path.join(workspaceRoot, '.continue'),
+  path.join(userHome, '.agents'),
+  path.join(userHome, '.claude')
+];
+
+// Helper to parse simple YAML frontmatter without external dependencies
+function parseFrontmatter(content) {
+  const lines = content.split(/\r?\n/);
+  const fm = {};
+  let inFM = false;
+  const fmLines = [];
+  
+  for (const line of lines) {
+    if (line.trim() === '---') {
+      if (!inFM) {
+        inFM = true;
+        continue;
+      } else {
+        break;
+      }
+    }
+    if (inFM) {
+      fmLines.push(line);
+    }
+  }
+
+  let currentKey = null;
+  for (const line of fmLines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Check if indent level is substantial (nested list or object)
+    const indent = line.search(/\S/);
+    
+    if (indent === 0) {
+      const match = line.match(/^([a-zA-Z0-9_-]+)\s*:\s*(.*)$/);
+      if (match) {
+        const key = match[1];
+        const val = match[2].trim();
+        
+        let cleanVal = val;
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+          cleanVal = val.slice(1, -1);
+        }
+        
+        if (val.startsWith('[') && val.endsWith(']')) {
+          cleanVal = val.slice(1, -1).split(',').map(s => s.trim().replace(/^['"]|['"]$/g, ''));
+        }
+        
+        fm[key] = cleanVal;
+        currentKey = key;
+      }
+    } else if (indent > 0 && currentKey) {
+      // Handle nested properties or array items
+      if (trimmed.startsWith('- ')) {
+        if (!Array.isArray(fm[currentKey])) {
+          fm[currentKey] = [];
+        }
+        fm[currentKey].push(trimmed.slice(2).trim().replace(/^['"]|['"]$/g, ''));
+      } else {
+        const childMatch = trimmed.match(/^([a-zA-Z0-9_-]+)\s*:\s*(.*)$/);
+        if (childMatch) {
+          if (typeof fm[currentKey] !== 'object' || Array.isArray(fm[currentKey])) {
+            fm[currentKey] = {};
+          }
+          const childKey = childMatch[1];
+          const childVal = childMatch[2].trim().replace(/^['"]|['"]$/g, '');
+          fm[currentKey][childKey] = childVal;
+        }
+      }
+    }
+  }
+  return fm;
+}
+
+function processSkillDir(skillDirPath) {
+  const skillFile = path.join(skillDirPath, 'SKILL.md');
+  if (!fs.existsSync(skillFile)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(skillFile, 'utf8');
+  const fm = parseFrontmatter(content);
+  
+  const skillId = fm.name || path.basename(skillDirPath);
+  const description = fm.description || 'No description provided';
+  
+  // Extract custom triggers/tags if defined, or infer them from keywords
+  let triggers = [];
+  if (fm.triggers) {
+    triggers = Array.isArray(fm.triggers) ? fm.triggers : [fm.triggers];
+  } else if (fm.metadata && fm.metadata.triggers) {
+    triggers = Array.isArray(fm.metadata.triggers) ? fm.metadata.triggers : [fm.metadata.triggers];
+  } else {
+    // Fallback only - explicit `triggers:` frontmatter (mandated by
+    // skill-creator/SKILL.md §4) should make this branch rare. Kept
+    // deliberately conservative: only the skill name plus the description's
+    // first sentence (not the whole prose block), a longer stopword list,
+    // and a length-5+ floor, so a generic skill description doesn't spam
+    // tier-router.js with broad words that fire on unrelated prompts.
+    const firstSentence = description.split(/[.!?]/)[0];
+    const STOPWORDS = new Set([
+      'with', 'from', 'this', 'that', 'your', 'about', 'some', 'than', 'then',
+      'prevent', 'resolved', 'skill', 'agent', 'using', 'which', 'these',
+      'those', 'their', 'there', 'where', 'when', 'while', 'after', 'before',
+      'again', 'other', 'every', 'being', 'would', 'could', 'should', 'still',
+      'first', 'never', 'always', 'ensure', 'provide', 'provided'
+    ]);
+    const words = (skillId + ' ' + firstSentence)
+      .toLowerCase()
+      .replace(/[^\w\s-]/g, ' ')
+      .split(/\s+/)
+      .filter(w => w.length >= 5 && !STOPWORDS.has(w));
+    triggers = [...new Set(words)].slice(0, 8);
+  }
+
+  return {
+    id: skillId,
+    dirPath: skillDirPath,
+    description,
+    triggers,
+    metadata: fm.metadata || {}
+  };
+}
+
+function register() {
+  const arg = process.argv[2];
+
+  if (arg === '--help' || arg === '-h') {
+    console.log(`Register self-evolve dynamic skills into every detected platform manifest.json.
+
+Usage:
+  node register-dynamic-skill.js              Scan .claude/harness-everything/skills/generated/ and register every skill found there.
+  node register-dynamic-skill.js <name>        Register only the skill folder named <name> under skills/generated/.
+  node register-dynamic-skill.js <path>        Register the skill folder at this literal path instead.
+
+Each skill folder needs a SKILL.md with 'name' and 'description' frontmatter (plus
+'triggers' - if omitted, triggers are inferred from the name and description, which
+is a conservative fallback, not a substitute for setting them explicitly). Writes to
+every already-bootstrapped platform's manifest.json (.claude/, .cursor/, .github/,
+.codex/, .continue/, plus the user-home ~/.agents and ~/.claude homes).`);
+    process.exit(0);
+  }
+
+  const generatedBaseDir = path.join(workspaceRoot, '.claude', 'harness-everything', 'skills', 'generated');
+  
+  let skillsToRegister = [];
+
+  if (arg) {
+    // Scenario A: Register specific skill ID or path
+    let skillPath = arg;
+    if (!fs.existsSync(skillPath)) {
+      skillPath = path.join(generatedBaseDir, arg);
+    }
+    if (fs.existsSync(skillPath)) {
+      const info = processSkillDir(skillPath);
+      if (info) skillsToRegister.push(info);
+    } else {
+      console.error(`[Error] Dynamic skill folder not found: ${arg}`);
+      process.exit(1);
+    }
+  } else {
+    // Scenario B: Scan whole generated folder
+    if (fs.existsSync(generatedBaseDir)) {
+      const subdirs = fs.readdirSync(generatedBaseDir, { withFileTypes: true });
+      for (const entry of subdirs) {
+        if (entry.isDirectory()) {
+          const dirPath = path.join(generatedBaseDir, entry.name);
+          const info = processSkillDir(dirPath);
+          if (info) skillsToRegister.push(info);
+        }
+      }
+    }
+  }
+
+  if (skillsToRegister.length === 0) {
+    console.log('[Info] No self-evolved dynamic skills found to register.');
+    return;
+  }
+
+  // Write to all detected manifests (auto-creating target directories if in workspace)
+  let count = 0;
+  for (const home of manifestHomes) {
+    const manifestPath = getManifestPath(home);
+    const parentDir = path.dirname(manifestPath);
+    const isRepoHome = home.startsWith(workspaceRoot);
+    if (fs.existsSync(parentDir) || isRepoHome) {
+      fs.mkdirSync(parentDir, { recursive: true });
+      for (const skill of skillsToRegister) {
+        recordGeneratedSkill(manifestPath, skill.id, skill.dirPath, skill.description, skill.triggers);
+      }
+      console.log(`[Success] Registered ${skillsToRegister.length} skill(s) to ${manifestPath}`);
+      count++;
+    }
+  }
+
+  if (count === 0) {
+    // Fallback: If no manifest path's directory existed, write to at least the standard home path
+    const fallbackHome = path.join(userHome, '.agents');
+    const manifestPath = getManifestPath(fallbackHome);
+    for (const skill of skillsToRegister) {
+      recordGeneratedSkill(manifestPath, skill.id, skill.dirPath, skill.description, skill.triggers);
+    }
+    console.log(`[Success] Registered ${skillsToRegister.length} skill(s) to fallback manifest ${manifestPath}`);
+  }
+}
+
+register();