In Place File Mutation

In-Place Code Mutation (Zero-Tempfile Architecture)

Overview

A common anti-pattern in naive AI coding workflows is creating temporary sidecar duplicate files (auth_new.ts, server_temp.py, index.backup.js) with the intention of later swapping them with the original file.

Creating temporary sidecar files causes severe workflow hazards:

1. Multi-Turn Cleanup Churn: Requires 3 to 4 turns (Write new file $\rightarrow$ Delete old file $\rightarrow$ Rename new file $\rightarrow$ Remove backup), wasting roundtrip tokens.
2. Broken Module Resolution: Compilers and bundlers (tsc, vite, pytest) pick up the duplicate files, triggering duplicate identifier and conflicting route errors.
3. Orphaned Garbage on Disk: If a task fails or aborts mid-stream, orphaned _temp files remain permanently committed to the repository.

The In-Place Code Mutation Protocol enforces direct, atomic file mutations in-place using replace_file_content or memory-buffered atomic filesystem writes.

Sidecar Tempfile Anti-Pattern vs. Direct In-Place Mutation

┌─────────────────────────────────────────────────────────────┐
│                 File Mutation Workflow Comparison           │
│                                                             │
│  Sidecar Tempfile Anti-Pattern (4 Turns / 8,200 Tokens):    │
│  • Turn 1: `write_to_file("auth_new.ts")` (Full file dump) │
│  • Turn 2: `run_command("mv auth.ts auth.bak")`             │
│  • Turn 3: `run_command("mv auth_new.ts auth.ts")`          │
│  • Turn 4: `run_command("rm auth.bak")`                     │
│  ↳ 4 Turns, 8,200 tokens billed, high risk of orphaned files│
│                                                             │
│  Direct In-Place Mutation (1 Turn / 45 Tokens):             │
│  • Turn 1: `replace_file_content("auth.ts", L42-45)`        │
│  ↳ 1 Turn, 45 tokens billed, 100% Filesystem Hygiene!       │
└─────────────────────────────────────────────────────────────┘

The 3 Rules of In-Place Mutation

1. Zero Sidecar File Creation

Never create files with suffixes like _temp, _new, _copy, or .bak inside the workspace tree. All modifications must be applied directly to the canonical source file path.

2. Use replace_file_content for Existing Files

Target the specific substring or lines requiring modification. The underlying editor runtime applies the change directly to the file buffer without creating duplicate files on disk.

3. Use scratch/ for Intermediate Scripts Only

If a temporary script (e.g. an AST refactorer or migration script) is needed, place it inside the dedicated scratch/ directory where it is explicitly isolated from the production build.

Atomic In-Place Mutation Mechanics (Python)

When building agent tool executors, perform in-place mutation atomically using temporary swap buffers in memory:

import os
from pathlib import Path

def mutate_file_in_place(target_path: Path, old_str: str, new_str: str) -> None:
    """Performs an atomic, memory-buffered in-place file mutation."""
    content = target_path.read_text(encoding="utf-8")
    
    if old_str not in content:
        raise ValueError(f"Target substring not found in {target_path}")
        
    updated_content = content.replace(old_str, new_str, 1)
    
    # Write to temp file in same directory, then atomic rename
    temp_target = target_path.with_suffix(f"{target_path.suffix}.tmp_atomic")
    try:
        temp_target.write_text(updated_content, encoding="utf-8")
        os.replace(temp_target, target_path)  # Atomic on POSIX and Windows
    finally:
        if temp_target.exists():
            temp_target.unlink()

Benchmark Comparison

Evaluation across 50 autonomous bug fixes and refactoring tasks:

Agent Operational Directive

MANDATORY: Agents must NEVER generate _temp, _new, or .bak duplicate files to execute edits. Apply mutations directly to the target file in-place using replace_file_content.