Document adaptive self-improvement test scope

Author: FabioMalpezzi

docs/agent-kv-context-fixes.md

@@ -223,6 +223,50 @@ Verification:
 - `make test-kv-cache-benefit`
 - `git status --short`
 
+## 7. Adaptive Self-Improvement E2E Scope
+
+This test demonstrates the agent loop, not a real DS4 code optimization.
+
+It means:
+
+- DS4 is given a temporary repository with a small failing Python project.
+- DS4 must inspect repository state, fix the bug, run the tests, inspect the
+  diff, checkpoint the context, restore it, and prove the tests still pass.
+- If the native Git tool is available, the prompt asks DS4 to use it for
+  `status` and `diff`.
+- If the native Git tool is not available, the same test falls back to the
+  existing `bash` path with `git status --short` and `git diff`.
+
+Before:
+
+```text
+context tools work in isolated calls -> less proof of agent-level usefulness
+```
+
+Now:
+
+```text
+agent fixes a controlled project -> checkpoints -> restores -> verifies state
+```
+
+The limitation is intentional. This test does not claim that DS4 found and
+optimized DS4's own C code. A stronger follow-up test should run against DS4
+itself: ask the agent to inspect the repository, choose one small measurable
+optimization, implement it, run the relevant benchmark or e2e check, inspect
+the diff, checkpoint, restore, and record whether the metric improved.
+
+That DS4-on-DS4 loop is the ideal product demonstration, but it is a slower and
+less deterministic test than this PR should require by default. The controlled
+temporary repository keeps this PR's regression signal clear while preserving a
+direct path to the stronger self-optimization loop.
+
+Verification:
+
+- `make test-agent-context-self-improvement`
+- The generated ledger records `git_status_mode`, `git_diff_mode`,
+  `context_checkpoint_before`, `context_checkpoint_after`,
+  `context_restore_used`, `tests_before_restore`, and `tests_after_restore`.
+
 ## Test Plan
 
 Run:
@@ -231,6 +275,7 @@ Run:
 make test
 make test-agent-context-compact-canary
 make test-kv-cache-benefit
+make test-agent-context-self-improvement
 git status --short
 ```
 

docs/agent-kv-context-tools.md

@@ -715,6 +715,49 @@ guard that checks whether compaction preserves facts explicitly marked as
 critical for the next action while those facts are pushed out of the recent
 verbatim tail.
 
+12. Adaptive context self-improvement e2e.
+
+Run the optional self-improvement target:
+
+```sh
+make test-agent-context-self-improvement
+```
+
+This target is intentionally separate from default `make test`: it requires a
+real model/backend and asks DS4 to operate a complete agent loop. The harness
+creates a temporary repository with a small failing Python project, then the
+prompt requires DS4 to:
+
+- create a context checkpoint before changing the project,
+- inspect repository status,
+- read and fix the failing code,
+- run the project test,
+- inspect the resulting diff,
+- create a second context checkpoint after the test passes,
+- restore from that checkpoint,
+- inspect repository status again,
+- run the test again,
+- write a ledger with the exact actions and final result.
+
+The Git inspection step is adaptive. If the model-visible schemas include the
+native Git tool, the prompt asks DS4 to use it for `status` and `diff`. If that
+tool is absent, the same prompt requires the existing `bash` path with
+`git status --short` and `git diff`. This keeps the context/KV branch
+independent from the Git-tool branch while still letting the same test exercise
+the native Git path after integration.
+
+This test is not a claim that DS4 has optimized DS4 itself. It is a controlled
+regression test for the agent loop shape: inspect, edit, test, diff,
+checkpoint, restore, retest, and record evidence.
+
+The stronger product demonstration should be a DS4-on-DS4 optimization loop:
+ask DS4 to inspect this repository, select one small measurable optimization,
+implement it, run the relevant benchmark or e2e check, inspect the source diff,
+checkpoint and restore the successful state, and record whether the metric
+improved. That is the right next target, but it should remain an optional slow
+evaluation because it is more expensive and less deterministic than a controlled
+temporary-repository regression.
+
 ### Resume Point: 2026-05-25
 
 The DS4-generated context loop was run successfully with: