From 6fcf8de0a1b122b32d918e7487976159d1b2d5e2 Mon Sep 17 00:00:00 2001
From: REPPL <77722411+REPPL@users.noreply.github.com>
Date: Sat, 18 Jul 2026 14:57:52 +0100
Subject: [PATCH] docs: warn against git operations concurrent with tooling
 runs

Concurrent heavy git activity (a worktree add during an in-flight go
test) once corrupted the working repo's state: core.bare flipped and an
isolated test fixture's git identity leaked into the local config. The
code-side hardening landed in #18; this records the operational
guardrail in CONTRIBUTING.md and AGENTS.md, the remaining prevention
item.

Closes #17

Assisted-by: Claude:claude-fable-5
---
 AGENTS.md       | 6 ++++++
 CONTRIBUTING.md | 6 ++++++
 2 files changed, 12 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 1448685..d58caf8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -34,6 +34,12 @@ Without `FERRY_BIN` the eval suite skips every behavioural test and passes.
 CI (`.github/workflows/ci.yml`) runs build, vet, `go test ./...`, race tests
 on the internal packages, and the full eval suite against a real Linux binary.
 
+Never run git-mutating operations (`git worktree add`, merges, rebases)
+against this repository while a `go test` or other tooling run is in flight
+against it — concurrent heavy git activity has corrupted the working repo's
+state (issue #17). One at a time; this also means no parallel subagents that
+touch git.
+
 ## Boundaries
 
 - Nothing under `$HOME` is ever symlinked: deployed files are regular-file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4110012..2ab98d3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,6 +27,12 @@ Without `FERRY_BIN` the eval suite skips every behavioural test and passes. A
 change is done only when `make build`, `gofmt -l .` (empty), `go vet ./...`, and
 `go test ./...` are all clean and the eval suite is green with `FERRY_BIN` set.
 
+Never run git-mutating operations (`git worktree add`, merges, rebases) against
+this repository while a `go test` or other tooling run is in flight against it.
+Concurrent heavy git activity has corrupted the working repository's state —
+`core.bare` flipped and an isolated test fixture's git identity leaked into the
+local config (issue #17). Let one finish before starting the other.
+
 ## Branches, commits, and PRs
 
 - Work on a branch and open a PR, so review and CI gate the merge. Keep commits