Add transactional SHA-bound replace_text

docs/dev/architecture.md

@@ -1,7 +1,7 @@
 # Yada architecture
 
 Yada is a deliberately small DeepSeek-native coding harness: one model loop,
-five tools, an append-only conversation, checked patch application, and a
+six tools, an append-only conversation, checked patch application, and a
 verification gate. This document describes the internal boundaries contributors
 must preserve.
 
@@ -34,7 +34,7 @@ run/cli.py
     │   │   └── tools/runner.py
     │   │       ├── environments/workspace.py
     │   │       ├── environments/approval.py
-    │   │       └── tools/{search,read,patch,command,finish}.py
+    │   │       └── tools/{search,read,replace,patch,command,finish}.py
     │   ├── models/base.py ← models/deepseek.py
     │   └── traces/jsonl.py ← traces/report.py
     └── evals/cli.py
@@ -94,12 +94,13 @@ without weakening the workspace and tool contracts.
 
 ## Tool system
 
-Yada exposes five tools:
+Yada exposes six tools:
 
 | Tool | Responsibility |
 | --- | --- |
 | `search_code` | Search repository text with ripgrep and a Python fallback. |
 | `read_file` | Return bounded, numbered text plus a SHA-256 content hash. |
+| `replace_text` | Apply exact unique replacements to existing UTF-8 files. |
 | `apply_patch` | Validate and apply a Git-style unified diff. |
 | `run_command` | Run an approved argv array and return bounded structured output. |
 | `finish` | End only after verification of the latest revision. |
@@ -126,6 +127,12 @@ This is an optimistic transaction: a file changed after the model read it is a
 conflict, not permission to apply a stale edit. Every successful patch increments
 the workspace revision and invalidates earlier verification.
 
+`replace_text` uses the same transaction rather than introducing another write
+path. It validates every SHA and exact unique match in memory, applies same-file
+edits in declaration order, generates a standard-library unified diff, and sends
+the complete result through `apply_patch`. Zero or ambiguous matches fail closed;
+no file changes until the generated multi-file patch passes validation.
+
 ## Commands and verification
 
 `run_command` accepts argv, not a shell string. It checks the executable

src/yada/agents/prompts.py

@@ -7,8 +7,8 @@
 
 Rules:
 1. Search before reading, and read a file before editing it.
-2. read_file returns a SHA-256. apply_patch requires the current SHA-256 for every
-   existing file it touches, or the literal NEW for a new file.
+2. read_file returns a SHA-256. replace_text and apply_patch require the current
+   SHA-256 for every existing file they touch; apply_patch uses NEW for a new file.
 3. Prefer small unified diffs. Do not rewrite unrelated code.
 4. Run the most relevant available tests after the last patch. A successful inspection
    command is not a test.
@@ -22,6 +22,7 @@
 Tool strategy:
 - search_code: locate symbols and references.
 - read_file: inspect bounded line ranges and obtain a file hash.
+- replace_text: make exact, unique, version-checked replacements in existing text.
 - apply_patch: make a version-checked unified-diff edit.
 - run_command: inspect or verify with an argv array; no shell syntax.
 - finish: submit only after the verification gate is satisfied.