@evomap/evolver 1.70.0-beta.1 → 1.70.0-beta.3

package/README.ja-JP.md

@@ -5,6 +5,7 @@
 [![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg)](https://nodejs.org/)
 [![GitHub last commit](https://img.shields.io/github/last-commit/EvoMap/evolver)](https://github.com/EvoMap/evolver/commits/main)
 [![GitHub issues](https://img.shields.io/github/issues/EvoMap/evolver)](https://github.com/EvoMap/evolver/issues)
+[![arXiv](https://img.shields.io/badge/arXiv-2604.15097-b31b1b.svg)](https://arxiv.org/abs/2604.15097)
 
 ![Evolver Cover](assets/cover.png)
 
@@ -22,6 +23,18 @@
 
 ---
 
+> **研究論文 — Evolver の理論的基盤**
+>
+> **From Procedural Skills to Strategy Genes: Towards Experience-Driven Test-Time Evolution** · [arXiv:2604.15097](https://arxiv.org/abs/2604.15097) · [PDF](https://arxiv.org/pdf/2604.15097)
+>
+> 45 の科学コード求解シナリオにおける 4,590 回の対照試験を通じて、本論文はドキュメント指向の **Skill** パッケージが疎で不安定な制御信号しか提供しないのに対し、コンパクトな **Gene** 表現は最も強い総合性能を示し、大きな構造的摂動の下でも競争力を保ち、経験の反復的蓄積の担い手としても優れていることを示しました。CritPt では、gene-evolved システムは組み合わせたベースモデルを 9.1% から 18.57% へ、17.7% から 27.14% へと引き上げました。
+>
+> Evolver はこの結論を実装に落とし込んだオープンソースエンジンです。GEP プロトコルの下で、エージェントの経験を場当たり的なプロンプトやスキルドキュメントではなく、Gene と Capsule として符号化します。*なぜ* Evolver が長いスキルドキュメントではなく Gene にこだわるのか疑問に思ったことがあるなら、読むべきはこの論文です。
+>
+> 応用事例を見たい方へ：[OpenClaw x EvoMap：CritPt 評価レポート](https://evomap.ai/blog/openclaw-critpt-report) では、OpenClaw エージェントが CritPt Physics Solver 上の 5 バージョン（Beta → v2.2）にわたって、同じ Gene ベース進化ループによってスコアを 0.00% から 18.57% まで押し上げる全過程を、トークンコストの軌跡、遺伝子活性化マップ、そして推論が再利用可能な Gene に圧縮されるときに現れる「トークンが上昇してから下降する」シグネチャとともに詳述しています。
+
+---
+
 > **「進化は任意ではない。適応するか、滅びるか。」**
 
 **3行で説明**

package/README.ko-KR.md

@@ -5,6 +5,7 @@
 [![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg)](https://nodejs.org/)
 [![GitHub last commit](https://img.shields.io/github/last-commit/EvoMap/evolver)](https://github.com/EvoMap/evolver/commits/main)
 [![GitHub issues](https://img.shields.io/github/issues/EvoMap/evolver)](https://github.com/EvoMap/evolver/issues)
+[![arXiv](https://img.shields.io/badge/arXiv-2604.15097-b31b1b.svg)](https://arxiv.org/abs/2604.15097)
 
 ![Evolver Cover](assets/cover.png)
 
@@ -22,6 +23,18 @@
 
 ---
 
+> **연구 논문 — Evolver의 이론적 기반**
+>
+> **From Procedural Skills to Strategy Genes: Towards Experience-Driven Test-Time Evolution** · [arXiv:2604.15097](https://arxiv.org/abs/2604.15097) · [PDF](https://arxiv.org/pdf/2604.15097)
+>
+> 45개의 과학 코드 풀이 시나리오에서 진행된 4,590회의 통제 실험을 통해, 본 논문은 문서 중심의 **Skill** 패키지가 희소하고 불안정한 제어 신호만 제공하는 반면, 컴팩트한 **Gene** 표현은 가장 강력한 전체 성능을 보이고 상당한 구조적 섭동에서도 경쟁력을 유지하며 경험의 반복적 축적을 담는 더 나은 매개체라는 것을 보여줍니다. CritPt에서 gene-evolved 시스템은 짝을 이룬 기본 모델을 9.1%에서 18.57%로, 17.7%에서 27.14%로 끌어올렸습니다.
+>
+> Evolver는 이 결과를 실제로 구현하는 오픈소스 엔진입니다. GEP 프로토콜 아래 에이전트의 경험을 임시 프롬프트나 스킬 문서가 아니라 Gene과 Capsule로 인코딩합니다. *왜* Evolver가 더 긴 스킬 문서 대신 Gene을 고집하는지 궁금했다면, 바로 이 논문을 읽어야 합니다.
+>
+> 적용 사례가 궁금하신가요? [OpenClaw x EvoMap: CritPt 평가 보고서](https://evomap.ai/blog/openclaw-critpt-report)는 동일한 Gene 기반 진화 루프가 OpenClaw 에이전트를 CritPt Physics Solver의 5개 버전(Beta → v2.2)에 걸쳐 0.00%에서 18.57%까지 끌어올리는 과정을, 전체 토큰 비용 궤적, 유전자 활성화 매핑, 그리고 추론이 재사용 가능한 Gene으로 압축될 때 나타나는 "토큰이 먼저 상승한 뒤 하강하는" 시그니처와 함께 단계별로 보여줍니다.
+
+---
+
 > **"진화는 선택이 아니다. 적응하거나, 도태되거나."**
 
 **한 줄 요약**

package/README.md

@@ -5,6 +5,7 @@
 [![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg)](https://nodejs.org/)
 [![GitHub last commit](https://img.shields.io/github/last-commit/EvoMap/evolver)](https://github.com/EvoMap/evolver/commits/main)
 [![GitHub issues](https://img.shields.io/github/issues/EvoMap/evolver)](https://github.com/EvoMap/evolver/issues)
+[![arXiv](https://img.shields.io/badge/arXiv-2604.15097-b31b1b.svg)](https://arxiv.org/abs/2604.15097)
 
 ![Evolver Cover](assets/cover.png)
 
@@ -22,6 +23,18 @@
 
 ---
 
+> **Research — The theory behind Evolver**
+>
+> **From Procedural Skills to Strategy Genes: Towards Experience-Driven Test-Time Evolution** · [arXiv:2604.15097](https://arxiv.org/abs/2604.15097) · [PDF](https://arxiv.org/pdf/2604.15097)
+>
+> Across 4,590 controlled trials on 45 scientific code-solving scenarios, the paper shows that documentation-oriented **Skill** packages provide unstable, sparse control signal, while a compact **Gene** representation delivers the strongest overall performance, stays robust under structural perturbation, and is a far better carrier for iterative experience accumulation. On CritPt, gene-evolved systems lift their paired base models from 9.1% to 18.57% and from 17.7% to 27.14%.
+>
+> Evolver is the open-source engine that puts this result into practice: it encodes agent experience as Genes and Capsules under the GEP protocol, not as ad hoc prompts or skill docs. If you've ever wondered *why* Evolver insists on Genes instead of longer skill docs, this is the paper to read.
+>
+> Want the applied version? [OpenClaw x EvoMap: CritPt Evaluation Report](https://evomap.ai/blog/openclaw-critpt-report) walks through how the same Gene-based evolution loop drives an OpenClaw agent from 0.00% to 18.57% on CritPt Physics Solver across five versions (Beta -> v2.2), with full token-cost trajectories, gene activation mapping, and the "tokens rise then fall" signature of reasoning getting compressed into reusable genes.
+
+---
+
 > **"Evolution is not optional. Adapt or die."**
 
 **Three lines**

package/README.zh-CN.md

@@ -5,6 +5,7 @@
 [![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg)](https://nodejs.org/)
 [![GitHub last commit](https://img.shields.io/github/last-commit/EvoMap/evolver)](https://github.com/EvoMap/evolver/commits/main)
 [![GitHub issues](https://img.shields.io/github/issues/EvoMap/evolver)](https://github.com/EvoMap/evolver/issues)
+[![arXiv](https://img.shields.io/badge/arXiv-2604.15097-b31b1b.svg)](https://arxiv.org/abs/2604.15097)
 
 ![Evolver Cover](assets/cover.png)
 
@@ -22,6 +23,18 @@
 
 ---
 
+> **研究论文 —— Evolver 背后的理论依据**
+>
+> **From Procedural Skills to Strategy Genes: Towards Experience-Driven Test-Time Evolution**（《从程序化技能到策略基因：面向经验驱动的测试时进化》）· [arXiv:2604.15097](https://arxiv.org/abs/2604.15097) · [PDF](https://arxiv.org/pdf/2604.15097)
+>
+> 论文在 45 个科学代码求解场景下完成 4,590 次对照实验，结论是：以文档为中心的 **Skill** 包控制信号稀疏且不稳定，而紧凑的 **Gene** 表示在整体表现上最强，在大幅结构扰动下仍有竞争力，并且是承载经验迭代积累的更好载体。在 CritPt 基准上，gene-evolved 系统将配对基座模型从 9.1% 提升到 18.57%，从 17.7% 提升到 27.14%。
+>
+> Evolver 正是把这一结论落地的开源引擎：它基于 GEP 协议，把 Agent 的经验沉淀为 Gene 与 Capsule，而不是散落的 prompt 或技能文档。如果你想知道 *为什么* Evolver 坚持使用 Gene 而不是更长的 skill 文档，这就是那篇该读的论文。
+>
+> 想看应用落地的样本？[OpenClaw x EvoMap：CritPt 评测报告](https://evomap.ai/blog/openclaw-critpt-report) 以 OpenClaw Agent 在 CritPt Physics Solver 上的五个版本演进（Beta → v2.2）为例，完整拆解了同一套 Gene 进化闭环如何把得分从 0.00% 推到 18.57%，并给出 token 成本轨迹、基因激活映射，以及推理被压缩成可复用基因后所呈现的「token 先升后降」特征。
+
+---
+
 > **"进化不是可选项，而是生存法则。"**
 
 **三句话概括**

package/assets/gep/candidates.jsonl

@@ -1,3 +1,3 @@
-{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-23T06:02:57.897Z","signals":["bounty_task","external_task","what","understand","really","dont","explanation.","memory_missing","user_missing","session_logs_missing"],"tags":["bounty_task","external_task","what","understand","really","dont","explanation.","memory_missing","user_missing","session_logs_missing","area:orchestration","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: bounty_task, external_task, what, understand, really, dont, explanation., memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}
-{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-23T06:03:00.033Z","signals":["bounty_task","external_task","human","new","very","grow","how","memory_missing","user_missing","session_logs_missing"],"tags":["bounty_task","external_task","human","new","very","grow","how","memory_missing","user_missing","session_logs_missing","area:orchestration","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: bounty_task, external_task, human, new, very, grow, how, memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}
-{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-23T06:03:01.960Z","signals":["memory_missing","user_missing","session_logs_missing"],"tags":["memory_missing","user_missing","session_logs_missing","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}
+{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-25T03:26:52.453Z","signals":["memory_missing","user_missing","session_logs_missing"],"tags":["memory_missing","user_missing","session_logs_missing","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}
+{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-25T03:26:54.382Z","signals":["memory_missing","user_missing","session_logs_missing"],"tags":["memory_missing","user_missing","session_logs_missing","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}
+{"type":"CapabilityCandidate","id":"cand_b9a66a5c","title":"Harden session log detection and fallback behavior","source":"signals","created_at":"2026-04-25T03:26:56.266Z","signals":["memory_missing","user_missing","session_logs_missing"],"tags":["memory_missing","user_missing","session_logs_missing","area:memory"],"shape":{"title":"Harden session log detection and fallback behavior","input":"Recent session transcript + memory snippets + user instructions","output":"A safe, auditable evolution patch guided by GEP assets","invariants":"Protocol order, small reversible patches, validation, append-only events","params":"Signals: memory_missing, user_missing, session_logs_missing","failure_points":"Missing signals, over-broad changes, skipped validation, missing knowledge solidification","evidence":"Signal present: session_logs_missing"}}

package/assets/gep/genes.json

@@ -78,7 +78,8 @@
         "perf_bottleneck",
         "capability_gap",
         "stable_success_plateau",
-        "external_opportunity"
+        "external_opportunity",
+        "bounty_task"
       ],
       "preconditions": [
         "at least one opportunity signal is present",
@@ -105,6 +106,43 @@
         "node scripts/validate-suite.js"
       ]
     },
+    {
+      "type": "Gene",
+      "id": "gene_gep_optimize_tool_usage",
+      "summary": "Optimize tool execution patterns by reducing redundant exec calls, improving tool selection strategy, and enforcing tool-use constraints to prevent bypass.",
+      "category": "optimize",
+      "signals_match": [
+        "high_tool_usage:exec",
+        "repeated_tool_usage:exec",
+        "tool_bypass",
+        "tool_loop",
+        "high_tool_usage"
+      ],
+      "preconditions": [
+        "agent repeatedly invokes the same tool (especially exec) without progress",
+        "tool execution bypass patterns detected",
+        "no active error signals (errors would take repair priority)"
+      ],
+      "strategy": [
+        "Analyze tool usage patterns to identify the root cause of repetition (wrong tool, missing context, or lack of guardrails)",
+        "Introduce strategy-level guardrails: prefer single-shot commands, batch related operations, add explicit retry limits",
+        "If tool_bypass detected, strengthen constraint enforcement in prompt assembly or tool routing",
+        "Estimate blast radius; changes should target tool routing, prompt constraints, or signal deduplication logic",
+        "Validate by confirming no regressions in existing tool tests and signal extraction accuracy",
+        "Solidify: record EvolutionEvent with intent=optimize, update Capsule on success"
+      ],
+      "constraints": {
+        "max_files": 15,
+        "forbidden_paths": [
+          ".git",
+          "node_modules"
+        ]
+      },
+      "validation": [
+        "node scripts/validate-modules.js ./src/gep/signals ./src/evolve",
+        "node scripts/validate-suite.js"
+      ]
+    },
     {
       "type": "Gene",
       "id": "gene_distilled_s2g-env-vars",

package/index.js

@@ -143,6 +143,24 @@ async function main() {
     }
 
     console.log('Starting evolver...');
+
+    // Preflight: fail fast if git is not on PATH. On Windows in particular
+    // a missing git binary can cause evolver to hang silently (see #394),
+    // because several cycle-critical steps shell out to git early (repo
+    // resolution, diff, blast-radius). Catching this up front makes the
+    // failure mode obvious.
+    try {
+      const { execSync } = require('child_process');
+      execSync('git --version', { stdio: 'ignore', timeout: 5000 });
+    } catch (_gitErr) {
+      console.error('');
+      console.error('[Preflight] Could not run "git --version". Evolver requires git to be installed and available on PATH.');
+      console.error('[Preflight] On Windows: install Git from https://git-scm.com/download/win and make sure `git --version` works in a fresh terminal.');
+      console.error('[Preflight] On macOS:   xcode-select --install  (or `brew install git`)');
+      console.error('[Preflight] On Linux:   sudo apt-get install -y git  (or your distro equivalent)');
+      console.error('');
+      process.exit(1);
+    }
     
     if (isLoop) {
         // Internal daemon loop (no wrapper required).
@@ -250,6 +268,12 @@ async function main() {
 
         // ATP: opt-in capability-gap auto-buyer (default OFF, must be explicitly enabled).
         try {
+          try {
+            const { runPrompt } = require('./src/atp/cliAutobuyPrompt');
+            await runPrompt();
+          } catch (promptErr) {
+            console.warn('[ATP-AutoBuyer] first-run prompt failed: ' + (promptErr && promptErr.message || promptErr));
+          }
           const autoBuyRaw = (process.env.EVOLVER_ATP_AUTOBUY || 'off').toLowerCase().trim();
           const autoBuyOn = autoBuyRaw === 'on' || autoBuyRaw === '1' || autoBuyRaw === 'true';
           if (autoBuyOn) {
@@ -698,7 +722,13 @@ async function main() {
       console.log('\n[Review] Rejected. Rolling back changes...');
       try {
         execSync('git checkout -- .', { cwd: repoRoot, encoding: 'utf8', timeout: 30000, maxBuffer: MAX_EXEC_BUFFER });
-        execSync('git clean -fd', { cwd: repoRoot, encoding: 'utf8', timeout: 30000, maxBuffer: MAX_EXEC_BUFFER });
+        // Preserve user state on reject: .env files, node_modules, runtime
+        // PID files, and a dedicated workspace/ dir (if one exists) MUST NOT
+        // be wiped by an automated rollback. Users have reported losing
+        // secrets and runtime caches to an aggressive git clean.
+        execSync('git clean -fd -e node_modules -e workspace -e .env -e ".env.*" -e "*.pid"', {
+          cwd: repoRoot, encoding: 'utf8', timeout: 30000, maxBuffer: MAX_EXEC_BUFFER,
+        });
         const evolDir = getEvolutionDir();
         const sp = path.join(evolDir, 'evolution_solidify_state.json');
         if (fs.existsSync(sp)) {
@@ -848,10 +878,30 @@ async function main() {
         fs.writeFileSync(path.join(outDir, 'SKILL.md'), data.content, 'utf8');
       }
 
+      const ALLOWED_SKILL_EXTENSIONS = new Set([
+        '.js', '.mjs', '.cjs', '.ts',
+        '.json', '.md', '.txt',
+        '.sh', '.py',
+        '.yml', '.yaml',
+      ]);
+      const MAX_SKILL_FILE_BYTES = 512 * 1024;
+
       const bundled = Array.isArray(data.bundled_files) ? data.bundled_files : [];
+      const skippedFiles = [];
       for (const file of bundled) {
         if (!file || !file.name || typeof file.content !== 'string') continue;
         const safeName = path.basename(file.name);
+        const ext = path.extname(safeName).toLowerCase();
+        if (!ALLOWED_SKILL_EXTENSIONS.has(ext)) {
+          console.warn('[fetch] Skipped skill file with disallowed extension: ' + safeName);
+          skippedFiles.push(safeName);
+          continue;
+        }
+        if (Buffer.byteLength(file.content, 'utf8') > MAX_SKILL_FILE_BYTES) {
+          console.warn('[fetch] Skipped skill file exceeding ' + MAX_SKILL_FILE_BYTES + ' bytes: ' + safeName);
+          skippedFiles.push(safeName);
+          continue;
+        }
         fs.writeFileSync(path.join(outDir, safeName), file.content, 'utf8');
       }
 
@@ -860,9 +910,9 @@ async function main() {
       console.log('  Version: ' + (data.version || '?'));
       console.log('  Files:   SKILL.md' + (bundled.length > 0 ? ', ' + bundled.map(f => f.name).join(', ') : ''));
       if (data.already_purchased) {
-        console.log('  Cost:    free (already purchased)');
+        console.log('  Fetch cost: free (already purchased)');
       } else {
-        console.log('  Cost:    ' + (data.credit_cost || 0) + ' credits');
+        console.log('  Fetch cost: ' + (data.credit_cost || 0) + ' credits');
       }
     } catch (error) {
       if (error && error.name === 'TimeoutError') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evomap/evolver",
-  "version": "1.70.0-beta.1",
+  "version": "1.70.0-beta.3",
   "description": "A GEP-powered self-evolution engine for AI agents. Features automated log analysis and Genome Evolution Protocol (GEP) for auditable, reusable evolution assets.",
   "main": "index.js",
   "bin": {

package/src/adapters/hookAdapter.js

@@ -6,6 +6,7 @@ const PLATFORMS = {
   cursor: { name: 'Cursor', configDir: '.cursor', detector: '.cursor' },
   'claude-code': { name: 'Claude Code', configDir: '.claude', detector: '.claude' },
   codex: { name: 'Codex', configDir: '.codex', detector: '.codex' },
+  kiro: { name: 'Kiro', configDir: '.kiro', detector: '.kiro' },
 };
 
 function detectPlatform(cwd) {
@@ -35,6 +36,7 @@ function loadAdapter(platformId) {
     case 'cursor': return require('./cursor');
     case 'claude-code': return require('./claudeCode');
     case 'codex': return require('./codex');
+    case 'kiro': return require('./kiro');
     default: return null;
   }
 }
@@ -163,7 +165,7 @@ async function setupHooks({ platform, cwd, force, uninstall, evolverRoot } = {})
   const platformId = platform || detectPlatform(effectiveCwd);
 
   if (!platformId) {
-    console.error('[setup-hooks] Could not detect platform. Use --platform=cursor|claude-code|codex');
+    console.error('[setup-hooks] Could not detect platform. Use --platform=cursor|claude-code|codex|kiro');
     return { ok: false, error: 'platform_not_detected' };
   }
 

package/src/adapters/kiro.js

@@ -0,0 +1,203 @@
+const fs = require('fs');
+const path = require('path');
+const { copyHookScripts, removeHookScripts } = require('./hookAdapter');
+
+const HOOK_SCRIPTS_DIR_NAME = 'hooks';
+const EVOLVER_MARKER = '<!-- evolver-evolution-memory -->';
+const HOOK_FILE_SUFFIX = '.kiro.hook';
+const HOOK_FILES = {
+  sessionStart: 'evolver-session-start.kiro.hook',
+  signalDetect: 'evolver-signal-detect.kiro.hook',
+  sessionEnd: 'evolver-session-end.kiro.hook',
+};
+
+function buildHookConfig(kind, scriptsBase) {
+  // Kiro has no dedicated sessionStart event; `promptSubmit` is the closest
+  // analogue. The session-start JS script itself guards against per-prompt
+  // re-injection via a session-scoped state file when
+  // EVOLVER_SESSION_START_DEDUP=1 is set (injected inline into the command
+  // because Kiro runCommand has no env field).
+  const sessionStartCmd = `EVOLVER_SESSION_START_DEDUP=1 node ${scriptsBase}/evolver-session-start.js`;
+  const hookTemplates = {
+    sessionStart: {
+      name: 'Evolver Session Start',
+      version: '1',
+      description:
+        'Reads recent evolution memory from the local memory graph and injects it as context when a prompt is submitted.',
+      when: { type: 'promptSubmit' },
+      then: {
+        type: 'runCommand',
+        command: sessionStartCmd,
+        timeout: 3,
+      },
+      _evolver_managed: true,
+    },
+    signalDetect: {
+      name: 'Evolver Signal Detect',
+      version: '1',
+      description:
+        'Detects evolution signals (errors, perf bottlenecks, capability gaps, test failures) in file content after write operations.',
+      when: { type: 'postToolUse', toolTypes: ['write'] },
+      then: {
+        type: 'runCommand',
+        command: `node ${scriptsBase}/evolver-signal-detect.js`,
+        timeout: 2,
+      },
+      _evolver_managed: true,
+    },
+    sessionEnd: {
+      name: 'Evolver Session End',
+      version: '1',
+      description:
+        'Records evolution outcome at session end by analyzing git diff stats and writing to the local memory graph.',
+      when: { type: 'agentStop' },
+      then: {
+        type: 'runCommand',
+        command: `node ${scriptsBase}/evolver-session-end.js`,
+        timeout: 8,
+      },
+      _evolver_managed: true,
+    },
+  };
+  return hookTemplates[kind];
+}
+
+function buildAgentsMdSection() {
+  return `${EVOLVER_MARKER}
+## Evolution Memory (Evolver)
+
+This project uses evolver for self-evolution. Hooks automatically:
+1. Inject recent evolution memory on prompt submit
+2. Detect evolution signals during file edits
+3. Record outcomes at session end
+
+For substantive tasks, call \`gep_recall\` before work and \`gep_record_outcome\` after.
+Signals: log_error, perf_bottleneck, user_feature_request, capability_gap, deployment_issue, test_failure.`;
+}
+
+function appendSectionToFile(filePath, marker, content) {
+  let existing = '';
+  try { existing = fs.readFileSync(filePath, 'utf8'); } catch { /* new file */ }
+  if (existing.includes(marker)) return false;
+  const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n\n' : '\n';
+  fs.writeFileSync(filePath, existing + separator + content + '\n', 'utf8');
+  return true;
+}
+
+function writeHookFile(hooksDir, fileName, config) {
+  const tmp = path.join(hooksDir, fileName + '.tmp');
+  const dest = path.join(hooksDir, fileName);
+  fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, dest);
+  return dest;
+}
+
+function isEvolverManagedHookFile(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8').trim();
+    if (!raw) return false;
+    const data = JSON.parse(raw);
+    if (data && data._evolver_managed === true) return true;
+    if (typeof data.name === 'string' && /^evolver\b/i.test(data.name)) return true;
+    if (data.then && typeof data.then.command === 'string' &&
+        /evolver-(session|signal)/.test(data.then.command)) return true;
+  } catch { /* treat as non-evolver */ }
+  return false;
+}
+
+function install({ configRoot, evolverRoot, force }) {
+  const kiroDir = path.join(configRoot, '.kiro');
+  const hooksDir = path.join(kiroDir, HOOK_SCRIPTS_DIR_NAME);
+  const agentsMdPath = path.join(configRoot, 'AGENTS.md');
+  const scriptsBase = '.kiro/hooks';
+
+  const hookPaths = Object.values(HOOK_FILES).map(name => path.join(hooksDir, name));
+
+  if (!force) {
+    const existingEvolverHook = hookPaths.find(p => fs.existsSync(p) && isEvolverManagedHookFile(p));
+    if (existingEvolverHook) {
+      console.log('[kiro] Evolver hooks already installed. Use --force to overwrite.');
+      return { ok: true, skipped: true };
+    }
+  }
+
+  fs.mkdirSync(hooksDir, { recursive: true });
+
+  const written = [];
+  for (const [kind, fileName] of Object.entries(HOOK_FILES)) {
+    const cfg = buildHookConfig(kind, scriptsBase);
+    const dest = writeHookFile(hooksDir, fileName, cfg);
+    written.push(dest);
+    console.log('[kiro] Wrote ' + dest);
+  }
+
+  const copied = copyHookScripts(hooksDir, path.join(evolverRoot, 'src', 'adapters'));
+  console.log('[kiro] Copied ' + copied.length + ' hook scripts to ' + hooksDir);
+
+  const injected = appendSectionToFile(agentsMdPath, EVOLVER_MARKER, buildAgentsMdSection());
+  if (injected) {
+    console.log('[kiro] Injected evolution section into ' + agentsMdPath);
+  }
+
+  console.log('[kiro] Installation complete.');
+  console.log('[kiro] Kiro auto-discovers *.kiro.hook files in .kiro/hooks/ -- no restart needed.');
+
+  return {
+    ok: true,
+    platform: 'kiro',
+    files: [...written, agentsMdPath, ...copied],
+  };
+}
+
+function uninstall({ configRoot }) {
+  const kiroDir = path.join(configRoot, '.kiro');
+  const hooksDir = path.join(kiroDir, HOOK_SCRIPTS_DIR_NAME);
+  const agentsMdPath = path.join(configRoot, 'AGENTS.md');
+
+  let changed = false;
+  let removedCount = 0;
+
+  if (fs.existsSync(hooksDir)) {
+    try {
+      const entries = fs.readdirSync(hooksDir);
+      for (const entry of entries) {
+        if (!entry.endsWith(HOOK_FILE_SUFFIX)) continue;
+        const full = path.join(hooksDir, entry);
+        if (isEvolverManagedHookFile(full)) {
+          try { fs.unlinkSync(full); removedCount++; changed = true; } catch { /* ignore */ }
+        }
+      }
+    } catch { /* ignore */ }
+  }
+
+  const scripts = removeHookScripts(hooksDir);
+  if (scripts > 0) changed = true;
+
+  try {
+    if (fs.existsSync(agentsMdPath)) {
+      let content = fs.readFileSync(agentsMdPath, 'utf8');
+      if (content.includes(EVOLVER_MARKER)) {
+        const idx = content.indexOf(EVOLVER_MARKER);
+        const nextSection = content.indexOf('\n## ', idx + EVOLVER_MARKER.length);
+        const endIdx = nextSection !== -1 ? nextSection : content.length;
+        content = content.slice(0, idx).trimEnd() + (nextSection !== -1 ? content.slice(endIdx) : '');
+        fs.writeFileSync(agentsMdPath, content.trimEnd() + '\n', 'utf8');
+        changed = true;
+      }
+    }
+  } catch { /* ignore */ }
+
+  console.log(changed
+    ? `[kiro] Uninstalled evolver hooks (${removedCount} hook files + ${scripts} scripts removed).`
+    : '[kiro] No evolver hooks found to uninstall.');
+
+  return { ok: true, removed: changed };
+}
+
+module.exports = {
+  install,
+  uninstall,
+  buildHookConfig,
+  isEvolverManagedHookFile,
+  HOOK_FILES,
+};

package/src/adapters/scripts/evolver-session-start.js

@@ -5,6 +5,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 
 function findEvolverRoot() {
   const candidates = [
@@ -58,7 +59,68 @@ function formatOutcome(entry) {
   return `[${icon}] ${ts} score=${score} signals=[${signals}] ${note}`.slice(0, 200);
 }
 
+// Dedup guard: on platforms like Kiro, the sessionStart-equivalent event
+// (`promptSubmit`) fires on every user message in a session. Without this
+// guard, recent memory would be re-injected on every prompt. We key the
+// dedup on (platform, cwd) with a short TTL so a fresh agent session within
+// the same workspace still gets the injection, but mid-session prompts do
+// not. Cursor/Claude Code/Codex have true sessionStart events and should
+// bypass this check (controlled by EVOLVER_SESSION_START_DEDUP env var,
+// which the Kiro adapter sets on the hook command line implicitly via the
+// runtime environment, and other adapters leave unset).
+function getDedupStatePath() {
+  const dir = process.env.EVOLVER_SESSION_STATE_DIR
+    || path.join(os.homedir(), '.evolver');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch { /* ignore */ }
+  return path.join(dir, 'session-start-state.json');
+}
+
+function shouldSkipInjection() {
+  // Only apply dedup when explicitly enabled (set by Kiro adapter) OR when
+  // we detect a per-prompt-firing platform via PROMPT_SUBMIT heuristic in
+  // stdin. The stdin is drained in main(), so we rely on env flag here.
+  const dedupEnabled = String(process.env.EVOLVER_SESSION_START_DEDUP || '').toLowerCase() === '1'
+    || String(process.env.EVOLVER_SESSION_START_DEDUP || '').toLowerCase() === 'true';
+  if (!dedupEnabled) return false;
+
+  const ttlMs = Number(process.env.EVOLVER_SESSION_START_DEDUP_TTL_MS) || (30 * 60 * 1000);
+  const key = process.cwd();
+  const statePath = getDedupStatePath();
+
+  let state = {};
+  try {
+    if (fs.existsSync(statePath)) {
+      state = JSON.parse(fs.readFileSync(statePath, 'utf8')) || {};
+    }
+  } catch { state = {}; }
+
+  const now = Date.now();
+  const last = state[key];
+  if (typeof last === 'number' && now - last < ttlMs) {
+    return true;
+  }
+
+  state[key] = now;
+  try {
+    for (const k of Object.keys(state)) {
+      if (typeof state[k] !== 'number' || now - state[k] > 24 * 60 * 60 * 1000) {
+        delete state[k];
+      }
+    }
+    const tmp = statePath + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(state), 'utf8');
+    fs.renameSync(tmp, statePath);
+  } catch { /* best-effort */ }
+
+  return false;
+}
+
 function main() {
+  if (shouldSkipInjection()) {
+    process.stdout.write(JSON.stringify({}));
+    return;
+  }
+
   const evolverRoot = findEvolverRoot();
   const graphPath = findMemoryGraph(evolverRoot);