# Webdev Agent OS v15 — Autonomous Evolution & Refactoring Engine

## Purpose

The Autonomous Evolution Engine turns the Product Digital Twin into a controlled modernization system. It helps plan and verify dependency upgrades, framework migrations, API changes, database evolution, architecture refactors, runtime-policy hardening, and technical-debt campaigns without treating production as an experiment.

The engine does not automatically approve or deploy consequential changes. It creates evidence, identifies blast radius, enforces verification, recommends canary and rollback decisions, and preserves human authority at the production boundary.

## Operating chain

```text
Digital Twin evidence
→ Evolution program
→ Change proposal
→ Blast-radius analysis
→ Compatibility matrix
→ Test-stage evidence
→ Human approval
→ Staged canary
→ Guardrail observations
→ Promote, pause, or rollback decision
→ Technical-debt and outcome learning
```

## Core records

### Evolution program

A program defines the modernization objective, Digital Twin, risk tolerance, capacity budget, constraints, success criteria, and accountable owner.

### Change proposal

A proposal records:

- Change type and intended target state
- Source artifacts and affected requirements
- Breaking changes and dependencies
- Migration steps
- Estimated hours and cost
- Rollback plan and triggers
- Approval and evidence state

Supported proposal types include dependency upgrades, framework upgrades, API evolution, database evolution, architecture refactors, technical debt, security hardening, and runtime-policy changes.

### Impact analysis

The engine expands the selected artifacts through requirements, dependencies, tests, deployments, telemetry, and incidents. It produces a risk classification, confidence score, blockers, compatibility requirements, and recommended verification steps.

### Compatibility checks

Compatibility evidence can cover runtimes, browsers, package peer dependencies, API consumers, database engines, build tools, and migration directions. `conditional` means the target is usable only when recorded mitigations are satisfied. It is not equivalent to unconditional compatibility.

### Test runs

Test stages may include:

- Unit
- Integration
- End-to-end
- Security
- Accessibility
- Performance
- Migration
- Rollback rehearsal

Passing test runs require evidence references. High-risk work requires broader verification than low-risk work.

### Canary records

A canary defines exposure, cohort, observation duration, approval, and measurable guardrails. A breached guardrail blocks promotion. The engine can recommend continue, pause, investigate, or rollback, but the promotion or rollback decision remains reviewer-controlled.

### Technical-debt items

Debt records connect maintenance problems to specific artifacts, requirements, effort, severity, and evolution proposals. This prevents “technical debt” from becoming an untraceable general complaint.

## Safety controls

- Proposal authors cannot approve their own changes.
- A proposal cannot be approved before impact analysis.
- A canary cannot be created until compatibility, required tests, approval, and rollback evidence are satisfied.
- A canary cannot start before reviewer approval.
- A canary cannot be promoted when a guardrail is breached.
- Promotion requires explicit evidence references.
- Passing tests cannot be recorded without evidence.
- Internal code-evolution evidence is unavailable to client roles.
- Example package, build, deployment, and runtime records remain labeled illustrative.

## API

```text
GET  /api/evolution
GET  /api/evolution/stats
GET  /api/evolution/export
POST /api/evolution/programs
POST /api/evolution/programs/:id/portfolio
POST /api/evolution/proposals
POST /api/evolution/proposals/:id/analyze
POST /api/evolution/proposals/:id/decision
POST /api/evolution/compatibility
POST /api/evolution/test-runs
POST /api/evolution/canaries
POST /api/evolution/canaries/:id/decision
POST /api/evolution/canaries/:id/start
POST /api/evolution/canaries/:id/observe
POST /api/evolution/proposals/:id/rollback-recommendation
POST /api/evolution/debt
POST /api/evolution/report
```

## CLI

```bash
npm run evolution:stats
npm run evolution:report
node scripts/evolution-cli.js view
node scripts/evolution-cli.js portfolio evolution-opportunity-recovery
node scripts/evolution-cli.js analyze evo-auth-boundary
node scripts/evolution-cli.js rollback evo-auth-boundary
```

## Data files

```text
config/evolution-seed.json
config/evolution-store.json
config/evolution-store.schema.json
scripts/evolution-core.js
scripts/evolution-cli.js
scripts/evolution-report.js
dashboard/evolution.js
reports/autonomous-evolution/
```

## Evidence boundary

The included store demonstrates the workflow with illustrative records. It does not prove that Node versions, package peers, browser targets, database engines, tests, builds, canaries, or production metrics have been verified against an external system. Replace fixture evidence with real repository, CI, deployment, and telemetry evidence before using it for a production decision.