Skip to main content

​
Protocol Overview

The Genome Evolution Protocol (GEP) defines three core asset types and the rules for selecting, applying, and validating evolution changes. Schema Version: 1.5.0

​
Asset Types

​
Gene

A Gene is a reusable strategy for handling specific problem patterns. Genes are selected by matching signals to the signals_match array.
​
type
string
required
Must be "Gene"
​
id
string
required
Unique identifier (e.g., gene_gep_repair_from_errors)
​
category
string
required
One of: repair, optimize, innovate
​
signals_match
array
required
Array of signal patterns this Gene handles (e.g., ["error", "exception", "failed"])
​
preconditions
array
Human-readable conditions for when this Gene applies
​
strategy
array
required
Step-by-step strategy for applying this Gene
​
constraints
object
required
Blast radius and safety constraints
​
validation
array
required
Commands that must pass before solidifying (e.g., ["node scripts/validate-modules.js ./src/evolve"])

​
Capsule

A Capsule is a proven solution with tracked outcomes and success streaks. Capsules are created after successful Gene applications.
​
type
string
required
Must be "Capsule"
​
id
string
required
Unique identifier (e.g., capsule_1770477654236)
​
trigger
array
required
Signals that triggered this Capsule’s creation
​
gene
string
required
ID of the Gene used to create this Capsule
​
summary
string
required
Human-readable summary of the change
​
confidence
number
required
Confidence score (0.0-1.0)
​
blast_radius
object
required
Actual impact: { files: number, lines: number }
​
outcome
object
required
Outcome tracking: { status: "success" | "failed", score: number }
​
success_streak
number
required
Consecutive successful applications (for reuse scoring)
​
env_fingerprint
object
required
Environment metadata (node version, platform, etc.)

​
EvolutionEvent

An EvolutionEvent is an immutable audit log entry representing a single evolution cycle.
​
type
string
required
Must be "EvolutionEvent"
​
id
string
required
Unique identifier (e.g., evt_1770477654236)
​
parent
string
ID of the parent event (forms evolution tree)
​
intent
string
required
One of: repair, optimize, innovate
​
signals
array
required
Signals that triggered this evolution
​
genes_used
array
required
IDs of Genes applied in this evolution
​
blast_radius
object
required
Actual impact: { files: number, lines: number }
​
outcome
object
required
Outcome: { status: "success" | "failed", score: number }
​
capsule_id
string
ID of the Capsule created (if successful)
​
validation_report_id
string
ID of the ValidationReport

​
Selector Logic

The Selector chooses the best Gene or Capsule for a given set of signals. Implementation: src/gep/selector.js

​
Selection Algorithm

1

Extract Signals

Parse logs, errors, and user instructions to extract signal keywords
2

Score Genes

Match signals against signals_match arrays; prefer Genes with higher overlap
3

Score Capsules

Match signals against trigger arrays; boost score by confidence * success_streak
4

Apply Memory Preference

If memory graph has successful history with a Gene/Capsule, boost its score
5

Select Winner

Choose the highest-scoring option; return selector JSON with reason

​
Example Selector Output

{
  "selected": "gene_gep_repair_from_errors",
  "reason": [
    "signals match gene.signals_match",
    "signals: log_error, exception, failed",
    "memory_graph: memory_prefer:gene_gep_repair_from_errors | gene_prior:0.667"
  ],
  "alternatives": ["gene_gep_innovate_from_opportunity"]
}

​
Validation Rules

​
Command Safety

All validation commands are gated by safety checks (src/gep/solidify.js):
  1. Prefix Whitelist: Only node, npm, or npx commands allowed
  2. No Command Substitution: Backticks and $(...) rejected
  3. No Shell Operators: ;, &, |, >, < rejected (except in quoted strings)
  4. Timeout: Each command limited to 180 seconds
  5. Scoped Execution: Commands run with cwd set to repo root

​
Validation Report

After validation, a ValidationReport is created: 
{
  "type": "ValidationReport",
  "id": "vr_1770477654235",
  "gene_id": "gene_gep_repair_from_errors",
  "commands": [
    {
      "command": "node scripts/validate-modules.js ./src/evolve",
      "ok": true,
      "stdout": "ok\n",
      "stderr": ""
    }
  ],
  "overall_ok": true,
  "duration_ms": 80
}

​
Protocol Constraints

​
Blast Radius Limits

Each Gene declares maximum impact: 
"constraints": {
  "max_files": 20,
  "forbidden_paths": [".git", "node_modules"]
}
Constraining the scope of changes ensures:
  • Safety: Prevents runaway modifications
  • Reviewability: Humans can audit changes quickly
  • Rollback Speed: Smaller changes are easier to revert
  • Broadcast Eligibility: Only small, safe Capsules are shared via A2A

​
Forbidden Paths

These paths are always forbidden, even if not declared in Gene constraints:
  • .git/
  • node_modules/
  • assets/gep/events.jsonl (audit log must remain immutable)
  • Protected source files (if configured)

​
A2A Broadcast Eligibility

For a Capsule to be broadcast via A2A protocol, it must meet:
  1. High Outcome Score: outcome.score >= 0.7
  2. Safe Blast Radius: files <= 5, lines <= 200
  3. Success Streak: success_streak >= 2
Implementation: src/gep/a2a.js:isCapsuleBroadcastEligible()

​
Asset Versioning

​
Schema Version

All assets include schema_version: "1.5.0" for forward compatibility.

​
Asset ID (Content Hash)

Each asset includes asset_id computed via SHA-256 of canonical JSON: 
// Example from contentHash.js
const canonicalJson = JSON.stringify(asset, sortKeys);
const hash = crypto.createHash('sha256').update(canonicalJson).digest('hex');
const assetId = 'sha256:' + hash;
This enables:
  • Deduplication: Identical assets share the same ID
  • Verification: Recipients can verify integrity
  • Caching: Assets can be cached by content hash

​
Signal Patterns

​
Common Signal Keywords

error, exception, failed, crash, timeout, unstable
protocol, gep, prompt, audit, reusable, perf_bottleneck
user_feature_request, capability_gap, external_opportunity, stable_success_plateau

​
Error Signature Normalization

Error messages are normalized for matching: 
// Example: "errsig:**TOOLRESULT**: { \"status\": \"error\" }"
// Normalized to: "errsig_norm:870c3a82"
This allows Capsules to match similar errors without exact text match.

​
Next Steps

Genes

Explore real Gene examples and strategy patterns

Capsules

See actual Capsules with outcome tracking

Build docs developers (and LLMs) love

Get started for freeTalk to us