# ADR-0002: Enhanced Edit — 9-Level Fuzzy Matching & Atomic Multi-Edit

**Status:** Accepted
**Date:** 2026-05-13
**Extension:** `extensions/enhanced-edit/` (~40 files)

## Problem

Built-in `edit` requires exact text match. LLM-generated `oldText` blocks drift on whitespace, escaping, and indentation. Single exact-match failure wastes a full turn. Multi-file edits lack atomicity — partial application leaves files inconsistent.

## Decision

Replace built-in `edit`/`write` with:

- **9-level fuzzy chain**: exact → rstrip → block anchor (Levenshtein) → whitespace-normalized → indent-flexible → escape-normalized → trimmed boundary → context-aware (50% threshold) → multi-occurrence
- **Atomic `multi_edit`**: preflights on in-memory buffer; all-or-nothing disk write; single LSP diagnostic pass at end
- **Codex `patch` mode**: unified diff hunks with fuzzy hunk location (exact → rstrip → trim → unicode-normalized)

## Alternatives

| Approach                         | Why Rejected                                 |
| -------------------------------- | -------------------------------------------- |
| Keep built-in                    | ~30% failure rate on whitespace drift alone  |
| Unified diff only (Gemini CLI)   | Line-number brittle; no fuzzy fallback       |
| Single threshold (Roo-Code, 10%) | Either too strict or too loose — no gradient |

## Trade-offs

More code (~40 files vs ~100 lines built-in) but eliminates the dominant edit failure mode. LSP feedback after every edit tightens the correction loop to <3s.

## References

- [Google Diff-Match-Patch](https://github.com/google/diff-match-patch/) — canonical fuzzy matching
- [Roo-Code multi-search-replace](https://github.com/RooCodeInc/Roo-Code/blob/main/src/core/diff/strategies/multi-search-replace.ts) — Levenshtein-based, 10% threshold
- [Gemini CLI fuzzy match recovery](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/tools/edit.ts) — `ENABLE_FUZZY_MATCH_RECOVERY=true`
