Skip to main content

​
Overview

Review mode adds a human approval step before solidifying evolution changes. This workflow is essential for production environments, sensitive codebases, or when you want to inspect changes before they’re committed.

​
What is Review Mode?

Review mode splits the evolution cycle into two phases:
  1. Generate: The evolver analyzes history, selects a Gene, and applies changes to the working directory
  2. Review: You inspect the changes (via git diff) and approve or reject them
Changes remain uncommitted and unstaged until you explicitly approve them with --approve.

​
When to Use Review Mode

Use review mode when:
  • Running evolver on production code
  • Testing new strategies or experimental Genes
  • Working in shared repositories
  • Learning how the evolver makes decisions
  • Debugging unexpected behavior
  • You want full control over what gets committed
Standard mode (without --review) applies and commits changes automatically. Only use this in isolated environments or when you fully trust the evolution process.

​
Basic Review Workflow

1

Run Evolution Cycle

Execute a normal run to generate changes:
node index.js
The evolver will analyze history, select a Gene, and apply changes to your working directory. Changes remain uncommitted.
2

Review Changes

Inspect the pending evolution:
node index.js review
This displays:
  • Selected Gene details (ID, category, summary, strategy)
  • Extracted signals that triggered evolution
  • Mutation metadata (category, risk level, rationale)
  • Blast radius estimate (files and lines changed)
  • Full git diff (staged and unstaged changes)
3

Make a Decision

Approve or reject the changes:
node index.js review --approve

​
Review Output Example

============================================================
[Review] Pending evolution run: evo_20260309_143022
============================================================

--- Gene ---
  ID:       error-handling-v2
  Category: robustness
  Summary:  Add comprehensive error handling and validation
  Strategy:
    1. Wrap risky operations in try-catch blocks
    2. Add input validation before processing
    3. Include descriptive error messages
    4. Log errors with context

--- Signals ---
  - repair_needed
  - validation_hardening
  - error_pattern_detected

--- Mutation ---
  Category:   repair
  Risk Level: low
  Rationale:  Prevent crashes from unhandled exceptions in file operations

--- Blast Radius Estimate ---
  Files changed: 3
  Lines changed: 47

--- Diff ---
=== Staged Changes ===
diff --git a/src/evolve.js b/src/evolve.js
index 1234567..abcdefg 100644
--- a/src/evolve.js
+++ b/src/evolve.js
@@ -45,7 +45,12 @@ function loadHistory() {
-  const data = fs.readFileSync(historyPath, 'utf8');
-  return JSON.parse(data);
+  try {
+    const data = fs.readFileSync(historyPath, 'utf8');
+    return JSON.parse(data);
+  } catch (error) {
+    console.error(`Failed to load history: ${error.message}`);
+    return [];
+  }
 }

============================================================

To approve and solidify:  node index.js review --approve
To reject and rollback:   node index.js review --reject

​
Approval Process

When you approve with --approve, the evolver:
  1. Runs the solidify command
  2. Executes Gene validation commands (if defined)
  3. Creates an evolution event record
  4. Commits changes if validation passes
  5. Rolls back if validation fails
node index.js review --approve
Expected output: 
[Review] Approved. Running solidify...

[SOLIDIFY] SUCCESS
{
  "id": "error-handling-v2",
  "category": "robustness",
  "applied": true,
  "validation_passed": true
}

​
Rejection Process

When you reject with --reject, the evolver:
  1. Runs git checkout -- . to discard unstaged changes
  2. Runs git clean -fd to remove untracked files
  3. Marks the run as rejected in state file
  4. Prevents the same evolution from being retried
node index.js review --reject
Expected output: 
[Review] Rejected. Rolling back changes...
[Review] Changes rolled back.
Rejection is reversible if you stashed changes using EVOLVER_ROLLBACK_MODE=stash. Check git stash list to recover rejected changes.

​
Checking for Pending Reviews

Run review without flags to check status: 
node index.js review
No pending changes: 
[Review] No pending evolution run to review.
Run "node index.js run" first to produce changes, then review before solidifying.
Already solidified: 
[Review] Last run has already been solidified. Nothing to review.

​
Manual Inspection

Before approving, you can inspect changes manually:

​
View Diff

git diff          # Unstaged changes
git diff --cached # Staged changes

​
Check Untracked Files

git ls-files --others --exclude-standard

​
Test Changes Locally

npm test          # Run test suite
node index.js     # Test evolver itself

​
Alternative: Review Flag

You can also use the --review flag directly on the run command: 
node index.js --review
This is equivalent to: 
node index.js run  # Apply changes
node index.js review  # Show review prompt
The --review flag displays the review interface but does NOT pause execution. You must still use --approve or --reject in a second command.

​
Review in Loop Mode

Review mode is incompatible with loop mode (--loop). Loop mode is designed for fully automated operation and bypasses human approval. If you need periodic reviews in production:
  1. Run single cycles via cron
  2. Send notifications to a review queue
  3. Require manual approval before the next run
# Cron job: run evolution every 6 hours
0 */6 * * * cd /path/to/evolver && node index.js && node index.js review --approve

​
Rollback Configuration

Control rollback behavior with EVOLVER_ROLLBACK_MODE:
ModeBehavior
hard (default)Use git reset --hard (destructive)
stashUse git stash (preserves changes for recovery)
noneSkip rollback entirely
EVOLVER_ROLLBACK_MODE=stash node index.js review --reject
Use stash mode in active development workspaces to preserve rejected changes for later analysis.

​
Best Practices

  1. Always review in production: Never run automated evolution on live systems without review gates
  2. Check blast radius: Large changes (>100 lines) deserve extra scrutiny
  3. Validate before approving: Run tests and manual checks before --approve
  4. Review Gene strategy: Understand why this Gene was selected and what it’s trying to do
  5. Track rejected runs: Use asset-log to understand patterns in rejected evolutions

​
Next Steps

Loop Mode

Automate continuous evolution cycles

Strategy Presets

Control evolution focus and intensity

Operations

Monitor and manage evolver lifecycle

Running Evolver

Back to standard run workflow

Build docs developers (and LLMs) love

Get started for freeTalk to us