Scratch File Isolation

Scratch Directory Isolation & Ephemeral Artifact Quarantine

Overview

When agents create temporary helper scripts (e.g., a one-off database migration verification, a JSON test payload generator, or an AST refactoring script), creating these files directly inside src/ or the project root causes severe operational hazards.

Root and source directory pollution causes:

1. Test Runner Collisions: Test runners (jest, pytest, cargo test) automatically discover and attempt to execute .scratch.js or test_temp.py files, causing false-positive CI failures.
2. Git Status Token Flooding: git status outputs 15 untracked scratch files, burning context tokens on every subsequent git check.
3. Accidental Production Commits: Orphaned scratch scripts get inadvertently staged and committed to production repositories.

The Scratch Directory Isolation Protocol establishes a dedicated, strictly ignored scratch/ sandbox for all temporary scripts and diagnostic artifacts.

Workspace Root Pollution vs. Dedicated Scratch Sandbox

┌─────────────────────────────────────────────────────────────┐
│                 Filesystem Sandbox Isolation                │
│                                                             │
│  Unquarantined Workspace Pollution (Anti-Pattern):          │
│  ├── src/                                                   │
│  │   ├── test_debug_script.py  <-- Pytest tries to run this!│
│  │   └── temp_payload.json     <-- Inadvertently committed! │
│  ├── refactor_helper.js        <-- Pollutes `git status`   │
│  ↳ 12 untracked files in git status, CI test suite fails    │
│                                                             │
│  Quarantined `scratch/` Sandbox:                            │
│  ├── scratch/                                               │
│  │   ├── refactor_helper.py    <-- Isolated from build / CI │
│  │   └── temp_payload.json     <-- Auto-ignored in .gitignore│
│  ├── src/ (100% Pristine Production Code)                   │
│  ↳ 0 Git pollution, 0 CI test collisions, clean environment │
└─────────────────────────────────────────────────────────────┘

The 3 Quarantine Rules

┌───────────────────────────────────────────────────────────────────────────┐
│ 1. ALL TEMPORARY CODE GOES TO `scratch/`                                  │
│    One-off scripts (AST transformers, debug logs) must live in `scratch/` │
│                                                                           │
│ 2. AUTO-IGNORE IN `.gitignore`                                            │
│    Ensure `/scratch/` and `.scratch/` are registered in root `.gitignore` │
│                                                                           │
│ 3. PERSISTENT ARTIFACT SCRATCH                                            │
│    For multi-turn session persistence, use:                               │
│    `<appDataDir>/brain/<conversation-id>/scratch/`                        │
└───────────────────────────────────────────────────────────────────────────┘

Production Agent Execution Workflow

Step 1: Write Ephemeral Script to scratch/

{
  "TargetFile": "scratch/verify_db_seed.py",
  "CodeContent": "import sqlite3\nconn = sqlite3.connect('app.db')\nprint(f'User Count: {conn.execute(\"SELECT COUNT(*) FROM users\").fetchone()[0]}')",
  "Overwrite": true,
  "Description": "Ephemeral DB count verification script"
}

Step 2: Execute via Terminal & Clean

# Run the quarantined script
python scratch/verify_db_seed.py

# Optional: Remove upon task completion or let conversation tear-down clean it
rm scratch/verify_db_seed.py

Benchmark Comparison

Evaluation across 50 autonomous engineering tasks requiring temporary verification scripts:

Agent Operational Directive

MANDATORY: Agents must NEVER write temporary scripts, one-off test runners, or mock data files directly into src/ or the repository root. Always create and execute temporary artifacts inside the dedicated scratch/ directory.