npm package: @novora/forge
Description: Self-evolution system for Claude Code - L1-L4 layers
Author: Novora
Latest version: 1.0.2

# @novora/forge

**Self-Evolution System for Claude Code**

A four-layer architecture for autonomous self-improvement, enabling Claude Code to evolve and optimize itself through iterative mutation, fitness evaluation, and human-in-the-loop approval.

## Quick Start

```bash
# Install
npm install @novora/forge

# Interactive setup (first-time users)
npm run init

# Or manual setup
npm run setup

# Initialize
import { createEvolutionOrchestrator } from '@novora/forge';

const orchestrator = createEvolutionOrchestrator({
  dataDirectory: './evolution-data',
  autoApprove: false,  // Human approval required
  fitnessThreshold: 0.7
});

await orchestrator.initialize();

// Run evolution cycle
const result = await orchestrator.runEvolutionCycle(`
  # Improve Error Handling

  Priority: high

  Description: Add comprehensive error handling to async functions.

  Criteria:
  - All async functions have try-catch blocks
  - Errors are logged with context
  - User-friendly error messages returned
`);

console.log(result.success ? 'Evolution applied!' : 'Evolution rejected');
```

## CLI Usage

```bash
# List pending reviews
forge review list

# Show review details
forge review show <id>

# Approve a review
forge review approve <id> "Looks good"

# Reject a review
forge review reject <id> "Fitness too low"

# Run evolution cycle
forge cycle "Add error handling to async functions"

# View system statistics
forge stats
```

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                          forge CLI                                  │
│  review list | show | approve | reject | stats | cycle             │
└───────────────────────────────┬─────────────────────────────────────┘
                                │
┌───────────────────────────────▼─────────────────────────────────────┐
│                     EvolutionOrchestrator                            │
│  runEvolutionCycle(requirement) → EvolutionResult                   │
└───────────────────────────────┬─────────────────────────────────────┘
                                │
    ┌───────────────────────────┼───────────────────────────┐
    │                           │                           │
┌───▼───────────────────┐  ┌────▼────────────────────┐  ┌────▼──────────────┐
│       L1: Metrics     │  │       L2: Experiment    │  │     L3: Evolution │
│                       │  │                        │  │                    │
│  MetricsRetention     │  │  RequirementsChannel   │  │  Coordinator       │
│  - recordCycle()      │  │  - ingestRequirement() │  │  - proposeMutation()│
│  - getLatestMetrics() │  │  - parseRequirement()   │  │  - evaluateFitness()│
│  - getAverageFitness() │  │                        │  │                    │
│                       │  │  ExperimentSnapshot    │  │  L3Review          │
│  CycleMetrics         │  │  - createSnapshot()    │  │  - createReview()  │
│  RetentionStats       │  │  - restoreSnapshot()   │  │  - approveReview() │
└───────────────────────┘  └────────────────────────┘  │  - rejectReview()  │
                                                      └────────────────────┘
                                                                │
                                                      ┌─────────▼──────────┐
                                                      │       L4: Meta     │
                                                      │                     │
                                                      │  L4Circuits        │
                                                      │  - performMetaReview()│
                                                      │  - generateInsights() │
                                                      │  - checkHealth()    │
                                                      └─────────────────────┘
```

### Layers

| Layer | Purpose | Key Components |
|-------|---------|----------------|
| **L1: Metrics** | Fitness data collection & retention | `MetricsRetentionManager`, `CycleMetrics` |
| **L2: Experiment** | Requirements parsing & state management | `RequirementsChannelManager`, `ExperimentSnapshotManager` |
| **L3: Evolution** | Mutation proposals & human approval | `SelfEvolutionCoordinator`, `L3ReviewInterface` |
| **L4: Meta-Review** | Higher-order reasoning & bias detection | `L4Circuits`, `MetaReviewResult` |

## Evolution Flow

```
1. INGEST REQUIREMENT
   ↓ (RequirementsChannelManager)

2. PROPOSE MUTATION
   ↓ (SelfEvolutionCoordinator)

3. EVALUATE FITNESS
   ↓ (MetricsRetentionManager + Coordinator)

4. CREATE REVIEW
   ↓ (L3ReviewInterface)

5. AWAIT APPROVAL
   ↓ (Human: approve/reject)

6. CREATE SNAPSHOT (for rollback)
   ↓ (ExperimentSnapshotManager)

7. APPLY MUTATION
   ↓ (SelfEvolutionCoordinator)

8. RECORD CYCLE METRICS
   ↓ (MetricsRetentionManager)

9. RETURN RESULT
```

## API Reference

### EvolutionOrchestrator

Main entry point for running evolution cycles.

```typescript
import { createEvolutionOrchestrator } from '@novora/forge';

const orchestrator = createEvolutionOrchestrator({
  dataDirectory: './evolution-data',  // Storage location
  autoApprove: false,                  // Require human approval
  fitnessThreshold: 0.7,                // Minimum fitness to auto-approve
  maxRetries: 3,                       // Max retries on failure
  snapshotBeforeApply: true            // Create snapshot before mutation
});

await orchestrator.initialize();
const result = await orchestrator.runEvolutionCycle(requirementText);
```

#### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `dataDirectory` | string | `'./evolution-data'` | Storage directory |
| `autoApprove` | boolean | `false` | Auto-approve above threshold |
| `fitnessThreshold` | number | `0.7` | Fitness threshold for auto-approve |
| `maxRetries` | number | `3` | Max retry attempts |
| `snapshotBeforeApply` | boolean | `true` | Create rollback snapshot |

#### Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `initialize()` | `Promise<void>` | Initialize all components |
| `runEvolutionCycle(text)` | `Promise<EvolutionResult>` | Run full evolution cycle |
| `getPendingReviews()` | `Promise<ReviewItem[]>` | List pending reviews |
| `approveReview(id, reviewer, notes)` | `Promise<void>` | Approve a review |
| `rejectReview(id, reviewer, notes)` | `Promise<void>` | Reject a review |
| `getStats()` | `Promise<Stats>` | Get system statistics |

### MetricsRetentionManager

Collects and retains fitness metrics across evolution cycles.

```typescript
import { createMetricsRetentionManager } from '@novora/forge';

const metrics = createMetricsRetentionManager({
  dataDirectory: './metrics-data',
  rawMetricsRetention: 30,      // cycles
  aggregatedRetention: 90,       // days
  historicalRetention: 12        // months
});

await metrics.initialize();

// Record cycle metrics
await metrics.recordCycle({
  cycle: 1,
  timestamp: new Date(),
  data: {
    fitnessScore: 0.85,
    performance: 0.8,
    accuracy: 0.9,
    efficiency: 0.85,
    stability: 0.8,
    adaptability: 0.9
  }
});

// Get latest metrics
const latest = await metrics.getLatestMetrics();

// Calculate average fitness
const avgFitness = await metrics.getAverageFitness();
```

### L3ReviewInterface

Human-in-the-loop approval workflow.

```typescript
import { createL3ReviewInterface } from '@novora/forge';

const review = createL3ReviewInterface({
  storageDirectory: './review-data',
  reviewExpirationHours: 24,
  requireNotesForRejection: true,
  maxPendingReviews: 100
});

await review.initialize();

// Create review
const reviewItem = await review.createReview(
  'mutation',
  'target-file.ts',
  'Add error handling',
  'orchestrator',
  'high',
  { proposalId: 'mut_123' }
);

// Approve
await review.approveReview(reviewItem.id, 'human-reviewer', 'Approved');

// Reject
await review.rejectReview(reviewItem.id, 'human-reviewer', 'Insufficient coverage');

// Get dashboard data
const dashboard = await review.getDashboardData();
```

### L4Circuits

Meta-review layer for bias detection and strategy optimization.

```typescript
import { createL4Circuits } from '@novora/forge';

const l4 = createL4Circuits({
  storageDirectory: './l4-storage',
  metaReviewThreshold: 0.8,
  learningConfidenceThreshold: 0.7,
  enableAutoAdjustment: true
});

await l4.initialize();

// Perform meta-review on L3 decisions
const metaResult = await l4.performMetaReview([
  { decision: 'approve', reviewer: 'alice', notes: 'Good' },
  { decision: 'approve', reviewer: 'bob', notes: 'OK' }
]);

console.log(metaResult.biasDetected);    // true/false
console.log(metaResult.biasTypes);       // ['confirmation-bias']
console.log(metaResult.recommendation);   // 'revise' | 'approve' | 'reject' | 'escalate'

// Generate learning insights
const insights = await l4.generateInsights(evolutionHistory);

// Check circuit health
const health = await l4.checkHealth();
console.log(health.overall);  // 0-1 score
```

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `FORGE_DATA_DIR` | `./evolution-data` | Base data directory |

### Retention Policy

Default retention for metrics data:

| Tier | Retention | Description |
|------|-----------|-------------|
| Raw | 30 cycles | Per-cycle detailed metrics |
| Aggregated | 90 days | Daily summary data |
| Historical | 12 months | Monthly trend analysis |

## Error Handling

```typescript
try {
  const result = await orchestrator.runEvolutionCycle(requirement);
} catch (error) {
  if (error instanceof EvolutionError) {
    console.log(`Evolution failed: ${error.code}`);
  }
}
```

### Error Types

| Error Class | Code | Description |
|-------------|------|-------------|
| `EvolutionError` | Base class | General evolution errors |
| `MutationNotFoundError` | `MUTATION_NOT_FOUND` | Proposal not found |
| `CycleNotFoundError` | `CYCLE_NOT_FOUND` | Evolution cycle not found |
| `FitnessError` | `FITNESS_ERROR` | Fitness evaluation failed |
| `ReviewError` | Base class | Review workflow errors |
| `ReviewNotFoundError` | `REVIEW_NOT_FOUND` | Review not found |
| `CircuitBreakerError` | `CIRCUIT_BREAKER_OPEN` | Safety circuit tripped |

## Testing

```bash
# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run performance benchmarks
npm run test:perf
```

## License

MIT

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Security

See [SECURITY.md](SECURITY.md) for security policy.