# henrymao2004/misevolve architecture

> Architecture diagram of the GitHub repository henrymao2004/misevolve, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/henrymao2004/misevolve
- Repository: https://github.com/henrymao2004/misevolve

## Overview

MisEvolve is a benchmark for measuring persistent safety failures in self-improving agent skills, with SafeEvolve governance as an evaluated intervention. Its principal workflow runs scheduled episode tasks through an agent harness and an evolution method, judges behavior and authored artifacts, and records results. The README documents benchmark scheduling and persistence probes, but benchmark files are absent from the supplied tree. The graph therefore shows the documented workflow without inventing their implementation; source excerpts are partial, so some internal links are omitted.

Main entry points: [`src/misevolve/methods`](https://github.com/henrymao2004/misevolve/tree/main/src/misevolve/methods) (Method harnesses), [`src/misevolve/run.py`](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/run.py) (Run orchestration), [`src/misevolve/harness.py`](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/harness.py) (Episode lifecycle), [`src/misevolve/methods/_backbone.py`](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/_backbone.py) (Method LLM access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiment["Experiment runtime"]
  node_run["Run orchestration<br/>[run.py]"]
  node_episode["Episode lifecycle<br/>[harness.py]"]
  node_task_data["Benchmark episodes"]
  node_backbones["Backbone config<br/>[backbones.py]"]
  node_method_backbone["Method LLM access<br/>[_backbone.py]"]
  node_results["Episode results"]
end

subgraph group_agents["Agent execution"]
  node_agent_contract["Agent runner contract<br/>[harness.py]"]
  node_sandbox["Container sandbox<br/>[ahz_sandbox.py]"]
  node_normalize["Trajectory normalization<br/>[_normalize.py]"]
  node_claude["Claude Code adapter"]
  node_codex["Codex adapter<br/>[codex_runner.py]"]
  node_hermes["Hermes adapter<br/>[hermes_runner.py]"]
  node_openclaw["OpenClaw adapter<br/>[openclaw_runner.py]"]
end

subgraph group_evolution["Skill evolution"]
  node_methods["Method harnesses"]
  node_autoskill["AutoSkill<br/>[autoskill.py]"]
  node_evoskill["EvoSkill<br/>[evoskill.py]"]
  node_skillclaw["SkillClaw<br/>[skillclaw.py]"]
  node_skillopt["SkillOpt<br/>[skillopt.py]"]
  node_skillsvote["SkillsVote<br/>[skillsvote.py]"]
  node_hermes_native["Hermes native<br/>[hermes_native.py]"]
  node_no_evolution["No evolution<br/>[no_evolution.py]"]
end

subgraph group_governance["Governance and judging"]
  node_governance_wrapper["Governance wrapper<br/>[base.py]"]
  node_safeevolve["SafeEvolve policy<br/>[safeevolve.py]"]
  node_audit_repair["Audit and repair<br/>[audit.py]"]
  node_lineage["Skill lineage<br/>[lineage.py]"]
  node_governance_stores[("Governed stores<br/>[stores.py]")]
  node_behavioral_judge["Behavioral judge<br/>[behavioral.py]"]
  node_artifact_judge["Artifact judge<br/>[artifact.py]"]
  node_judge_config["Judge configuration<br/>[config.py]"]
end

node_researcher(("Benchmark operator"))

node_researcher -->|"starts run"| node_run
node_run -->|"runs episode"| node_episode
node_task_data -.->|"supplies tasks"| node_episode
node_episode -->|"executes tasks"| node_agent_contract
node_episode -->|"evolves skills"| node_methods
node_episode -->|"judges trajectories"| node_behavioral_judge
node_run -->|"configures judge"| node_behavioral_judge
node_run -->|"configures judge"| node_artifact_judge
node_episode -->|"produces rows"| node_results
node_backbones -.->|"resolves settings"| node_run
node_agent_contract -.->|"runs isolated tasks"| node_sandbox
node_claude -->|"implements"| node_agent_contract
node_codex -->|"implements"| node_agent_contract
node_hermes -->|"implements"| node_agent_contract
node_openclaw -->|"implements"| node_agent_contract
node_claude -->|"dispatches task"| node_sandbox
node_codex -->|"dispatches task"| node_sandbox
node_hermes -->|"dispatches task"| node_sandbox
node_claude -->|"normalizes output"| node_normalize
node_codex -->|"normalizes output"| node_normalize
node_hermes -->|"normalizes output"| node_normalize
node_openclaw -->|"normalizes output"| node_normalize
node_methods -->|"registers method"| node_autoskill
node_methods -->|"registers method"| node_evoskill
node_methods -->|"registers method"| node_skillclaw
node_methods -->|"registers method"| node_skillopt
node_methods -->|"registers method"| node_skillsvote
node_methods -->|"registers method"| node_hermes_native
node_methods -->|"registers method"| node_no_evolution
node_autoskill -->|"calls model"| node_method_backbone
node_evoskill -->|"calls model"| node_method_backbone
node_skillclaw -->|"calls model"| node_method_backbone
node_skillopt -->|"calls model"| node_method_backbone
node_skillsvote -->|"calls model"| node_method_backbone
node_method_backbone -->|"uses resolved model"| node_backbones
node_governance_wrapper -->|"wraps method"| node_methods
node_safeevolve -->|"implements policy"| node_governance_wrapper
node_safeevolve -->|"audits and repairs"| node_audit_repair
node_safeevolve -->|"tracks lineage"| node_lineage
node_governance_wrapper -->|"uses store"| node_governance_stores
node_run -->|"selects governance"| node_governance_wrapper
node_behavioral_judge -->|"loads settings"| node_judge_config
node_artifact_judge -->|"loads settings"| node_judge_config
node_run -->|"judges authored skills"| node_artifact_judge

click node_run "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/run.py"
click node_episode "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/harness.py"
click node_backbones "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/backbones.py"
click node_method_backbone "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/_backbone.py"
click node_agent_contract "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/harness.py"
click node_sandbox "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/ahz_sandbox.py"
click node_normalize "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/adapters/_normalize.py"
click node_claude "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/adapters/claudecode_runner.py"
click node_codex "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/adapters/codex_runner.py"
click node_hermes "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/adapters/hermes_runner.py"
click node_openclaw "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/adapters/openclaw_runner.py"
click node_methods "https://github.com/henrymao2004/misevolve/tree/main/src/misevolve/methods"
click node_autoskill "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/autoskill.py"
click node_evoskill "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/evoskill.py"
click node_skillclaw "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/skillclaw.py"
click node_skillopt "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/skillopt.py"
click node_skillsvote "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/skillsvote.py"
click node_hermes_native "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/hermes_native.py"
click node_no_evolution "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/no_evolution.py"
click node_governance_wrapper "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/governance/base.py"
click node_safeevolve "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/governance/safeevolve.py"
click node_audit_repair "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/governance/audit.py"
click node_lineage "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/governance/lineage.py"
click node_governance_stores "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/governance/stores.py"
click node_behavioral_judge "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/judges/behavioral.py"
click node_artifact_judge "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/judges/artifact.py"
click node_judge_config "https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/judges/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_run,node_episode,node_task_data,node_backbones,node_method_backbone,node_results toneBlue
class node_agent_contract,node_sandbox,node_normalize,node_claude,node_codex,node_hermes,node_openclaw toneAmber
class node_methods,node_autoskill,node_evoskill,node_skillclaw,node_skillopt,node_skillsvote,node_hermes_native,node_no_evolution toneMint
class node_governance_wrapper,node_safeevolve,node_audit_repair,node_lineage,node_governance_stores,node_behavioral_judge,node_artifact_judge,node_judge_config toneRose
class node_researcher toneIndigo
```

## Components

### Experiment runtime

- [Run orchestration](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/run.py): `src/misevolve/run.py`
- [Episode lifecycle](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/harness.py): `src/misevolve/harness.py`
- **Benchmark episodes**
- [Backbone config](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/backbones.py): `src/misevolve/backbones.py`
- [Method LLM access](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/_backbone.py): `src/misevolve/methods/_backbone.py`
- **Episode results**

### Agent execution

- [Agent runner contract](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/harness.py): `src/misevolve/harness.py`
- [Container sandbox](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/ahz_sandbox.py): `src/misevolve/ahz_sandbox.py`
- [Trajectory normalization](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/adapters/_normalize.py): `src/misevolve/adapters/_normalize.py`
- [Claude Code adapter](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/adapters/claudecode_runner.py): `src/misevolve/adapters/claudecode_runner.py`
- [Codex adapter](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/adapters/codex_runner.py): `src/misevolve/adapters/codex_runner.py`
- [Hermes adapter](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/adapters/hermes_runner.py): `src/misevolve/adapters/hermes_runner.py`
- [OpenClaw adapter](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/adapters/openclaw_runner.py): `src/misevolve/adapters/openclaw_runner.py`

### Skill evolution

- [Method harnesses](https://github.com/henrymao2004/misevolve/tree/main/src/misevolve/methods): `src/misevolve/methods`
- [AutoSkill](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/autoskill.py): `src/misevolve/methods/autoskill.py`
- [EvoSkill](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/evoskill.py): `src/misevolve/methods/evoskill.py`
- [SkillClaw](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/skillclaw.py): `src/misevolve/methods/skillclaw.py`
- [SkillOpt](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/skillopt.py): `src/misevolve/methods/skillopt.py`
- [SkillsVote](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/skillsvote.py): `src/misevolve/methods/skillsvote.py`
- [Hermes native](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/hermes_native.py): `src/misevolve/methods/hermes_native.py`
- [No evolution](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/methods/no_evolution.py): `src/misevolve/methods/no_evolution.py`

### Governance and judging

- [Governance wrapper](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/governance/base.py): `src/misevolve/governance/base.py`
- [SafeEvolve policy](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/governance/safeevolve.py): `src/misevolve/governance/safeevolve.py`
- [Audit and repair](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/governance/audit.py): `src/misevolve/governance/audit.py`
- [Skill lineage](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/governance/lineage.py): `src/misevolve/governance/lineage.py`
- [Governed stores](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/governance/stores.py): `src/misevolve/governance/stores.py`
- [Behavioral judge](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/judges/behavioral.py): `src/misevolve/judges/behavioral.py`
- [Artifact judge](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/judges/artifact.py): `src/misevolve/judges/artifact.py`
- [Judge configuration](https://github.com/henrymao2004/misevolve/blob/main/src/misevolve/judges/config.py): `src/misevolve/judges/config.py`

### Other components

- **Benchmark operator**

## Connections

- Benchmark operator → Run orchestration: starts run (evidence: `README.md`)
- Run orchestration → Episode lifecycle: runs episode (evidence: `src/misevolve/run.py`)
- Benchmark episodes → Episode lifecycle: supplies tasks (evidence: `README.md`)
- Episode lifecycle → Agent runner contract: executes tasks (evidence: `src/misevolve/harness.py`)
- Episode lifecycle → Method harnesses: evolves skills (evidence: `README.md`)
- Episode lifecycle → Behavioral judge: judges trajectories (evidence: `src/misevolve/harness.py`)
- Run orchestration → Behavioral judge: configures judge (evidence: `src/misevolve/run.py`)
- Run orchestration → Artifact judge: configures judge (evidence: `src/misevolve/run.py`)
- Episode lifecycle → Episode results: produces rows (evidence: `src/misevolve/harness.py`)
- Backbone config → Run orchestration: resolves settings (evidence: `README.md`)
- Agent runner contract → Container sandbox: runs isolated tasks (evidence: `README.md`)
- Claude Code adapter → Agent runner contract: implements (evidence: `src/misevolve/adapters/claudecode_runner.py`)
- Codex adapter → Agent runner contract: implements (evidence: `src/misevolve/adapters/codex_runner.py`)
- Hermes adapter → Agent runner contract: implements (evidence: `src/misevolve/adapters/hermes_runner.py`)
- OpenClaw adapter → Agent runner contract: implements (evidence: `src/misevolve/adapters/openclaw_runner.py`)
- Claude Code adapter → Container sandbox: dispatches task (evidence: `src/misevolve/adapters/claudecode_runner.py`)
- Codex adapter → Container sandbox: dispatches task (evidence: `src/misevolve/adapters/codex_runner.py`)
- Hermes adapter → Container sandbox: dispatches task (evidence: `src/misevolve/adapters/hermes_runner.py`)
- Claude Code adapter → Trajectory normalization: normalizes output (evidence: `src/misevolve/adapters/claudecode_runner.py`)
- Codex adapter → Trajectory normalization: normalizes output (evidence: `src/misevolve/adapters/codex_runner.py`)
- Hermes adapter → Trajectory normalization: normalizes output (evidence: `src/misevolve/adapters/hermes_runner.py`)
- OpenClaw adapter → Trajectory normalization: normalizes output (evidence: `src/misevolve/adapters/openclaw_runner.py`)
- Method harnesses → AutoSkill: registers method (evidence: `src/misevolve/methods/__init__.py`)
- Method harnesses → EvoSkill: registers method (evidence: `src/misevolve/methods/__init__.py`)
- Method harnesses → SkillClaw: registers method (evidence: `src/misevolve/methods/__init__.py`)
- Method harnesses → SkillOpt: registers method (evidence: `src/misevolve/methods/__init__.py`)
- Method harnesses → SkillsVote: registers method (evidence: `src/misevolve/methods/__init__.py`)
- Method harnesses → Hermes native: registers method (evidence: `src/misevolve/methods/__init__.py`)
- Method harnesses → No evolution: registers method (evidence: `src/misevolve/methods/__init__.py`)
- AutoSkill → Method LLM access: calls model (evidence: `src/misevolve/methods/autoskill.py`)
- EvoSkill → Method LLM access: calls model (evidence: `src/misevolve/methods/evoskill.py`)
- SkillClaw → Method LLM access: calls model (evidence: `src/misevolve/methods/skillclaw.py`)
- SkillOpt → Method LLM access: calls model (evidence: `src/misevolve/methods/skillopt.py`)
- SkillsVote → Method LLM access: calls model (evidence: `src/misevolve/methods/skillsvote.py`)
- Method LLM access → Backbone config: uses resolved model (evidence: `src/misevolve/methods/_backbone.py`)
- Governance wrapper → Method harnesses: wraps method (evidence: `src/misevolve/governance/base.py`)
- SafeEvolve policy → Governance wrapper: implements policy (evidence: `src/misevolve/governance/safeevolve.py`)
- SafeEvolve policy → Audit and repair: audits and repairs (evidence: `src/misevolve/governance/safeevolve.py`)
- SafeEvolve policy → Skill lineage: tracks lineage (evidence: `src/misevolve/governance/safeevolve.py`)
- Governance wrapper → Governed stores: uses store (evidence: `src/misevolve/governance/base.py`)
- Run orchestration → Governance wrapper: selects governance (evidence: `src/misevolve/run.py`)
- Behavioral judge → Judge configuration: loads settings (evidence: `src/misevolve/judges/behavioral.py`)
- Artifact judge → Judge configuration: loads settings (evidence: `src/misevolve/judges/artifact.py`)
- Run orchestration → Artifact judge: judges authored skills (evidence: `src/misevolve/run.py`)
