# Webdev Agent OS v4 — Autonomous Repair Loop

The Autonomous Repair Loop turns an Automated Inspector report into a staged, reviewable, verified, and reversible patch set.

It is deliberately not an unrestricted code-writing bot. The system separates low-risk mechanical repairs from business logic and other changes that require human judgment.

## Operating sequence

1. **Load evidence** — use a Webdev Agent inspection report containing routes, findings, screenshots, and scorecard evidence.
2. **Map source** — associate each route with a local source file.
3. **Stage a copy** — duplicate the source into `source-before` and `source-after` workspaces. The original source is not changed.
4. **Propose repairs** — apply supported, evidence-backed transformations only to the staged `source-after` copy.
5. **Generate patches** — write a patch artifact for every created or modified file.
6. **Verify** — serve the staged repaired copy with the proposed security-header policy and run the Automated Inspector again.
7. **Compare** — calculate score, finding, blocker, route, and screenshot differences.
8. **Review** — inspect the repair report, repair plan, patch files, remaining findings, and manual-review queue.
9. **Approve** — require explicit human authorization before touching the original source.
10. **Apply safely** — confirm every original file hash still matches the plan, create a backup, and write only conflict-free files.
11. **Roll back** — restore the backup when requested.

## Supported low-risk repair classes

The v4 rule engine can currently propose repairs for:

- Missing document language
- Missing responsive viewport metadata
- Missing page descriptions
- Missing image alternatives
- Unlabeled form controls
- Missing main landmarks
- Missing H1 headings
- Skipped H4 heading transitions
- Absent action-oriented controls on simple content pages
- Static demonstration-only `console.error` statements
- Failed image resources that can be replaced with a local placeholder
- Missing favicon declarations
- Common horizontal-overflow patterns
- Missing static HTML routes, through an explicit recovery placeholder
- Common response security headers, through IIS and static-host policy files

The engine does not silently rewrite authentication, authorization, payments, database behavior, API contracts, private data handling, destructive actions, or core business rules.

## Safety controls

### Isolated workspace

Planning and verification operate against copied source directories:

```text
workspace/
  source-before/
  source-after/
```

### Explicit approval

Application fails unless the caller supplies an explicit approval value. In the Control Center, the operator must check the approval statement and then press **Approve and apply**.

### Stale-source protection

Every planned file records its original SHA-256 hash. If the source changed after planning, that file is reported as a conflict and is not overwritten.

### Backup and rollback

Before an existing file is changed, it is copied into a timestamped backup directory. Generated files are removed during rollback when they did not exist before application.

### Human-review queue

Unsupported, ambiguous, or higher-risk findings are preserved as manual-review items rather than being disguised as completed repairs.

## Generated artifacts

Each repair workspace contains:

```text
repair-plan.json
repair-plan.md
repair-report.json
repair-report.md
repair-report.html
before-report.json
patches/
workspace/
  source-before/
  source-after/
verification/
  inspection-after/
backup/                 # created only after approved application
```

## Command line

Create and verify a repair plan without changing source:

```bash
node scripts/repair-site.js loop \
  --source examples/inspection-target \
  --report examples/automated-inspector/report.json \
  --output reports/repair-demo
```

Create a plan only:

```bash
node scripts/repair-site.js plan --source ./public --report ./reports/site/report.json --output ./reports/site-repair
```

Re-run staged verification:

```bash
node scripts/repair-site.js verify --plan ./reports/site-repair/repair-plan.json
```

Apply after review:

```bash
node scripts/repair-site.js apply \
  --plan ./reports/site-repair/repair-plan.json \
  --approve \
  --approved-by "Responsible owner"
```

Roll back:

```bash
node scripts/repair-site.js rollback --plan ./reports/site-repair/repair-plan.json
```

## Control Center

Start the full local service:

```bash
npm run serve
```

Then open `http://127.0.0.1:8080/dashboard/` and use:

1. **Automated Inspector** to run or import evidence.
2. **Repair Loop** to specify the local source directory.
3. **Generate and verify repair plan** to build an isolated patch set.
4. The report links to review evidence and patches.
5. The approval gate to apply verified changes.
6. **Roll back applied changes** when restoration is required.

Imported repair reports are review-only because they do not have a live local repair job or trusted source mapping.

## Verification result model

The comparison records:

- Before and after quality score
- Score delta
- Before and after finding totals
- Resolved findings
- Remaining findings
- Newly introduced findings
- Before and after blocking findings
- Overall outcome: `improved` or `needs-review`

A better score does not automatically authorize release. The normal quality audit and human release gate still apply.

## Current boundary

v4 is strongest on static HTML and straightforward content sites. It creates useful patch infrastructure for larger applications, but complex React, Express, database, authentication, and workflow repairs should be implemented through architecture-aware adapters in future versions.