Evidence for the agent-isolation rule from the swept side, and an answer to its two open questions

[ptr727]

The hub's TODO.md already queues the rule that an agent works only in its own checkout, and records one side of the incident that motivated it: "a blanket add swept a second agent's in-progress registration work into an unrelated commit and pushed it, and the work survived only because it was rescued and restored by hand afterwards."

I was the second agent. This is the other side of the same event, filed because the entry leaves two questions open and the losing side has evidence the sweeping side cannot see.

What it looked like from inside the swept session

Working on the Blog registration that became #547, I was editing directly in /home/pieter/ProjectTemplate rather than a clone of my own. Over about twenty minutes:

1. The checkout switched branches under me three times, ledger-post-promotion to develop to agent-isolation-and-hub-tooling. I noticed only because a git log disagreed with one I had run minutes earlier.
2. My registry/repos.json edit disappeared and was silently reverted. I re-applied it, and spec/validate.py went from 22 cataloged back to 21, which is the only reason I caught it.
3. My new reports/blog/audit.md vanished entirely, along with an edit to reports/conformance-matrix.md.
4. My branch and a regenerated reports/divergences.md were left sitting in the other agent's tree, where they were not wanted.

None of that was visible as a conflict. Every command on both sides was individually correct.

The two open questions, from the losing side

"One checkout per agent, or one checkout per task." Per task, and the evidence is that this session hit the hazard without a second agent involved. The shell working directory persisted across tool calls in a way I misread, and a git mv I intended for the hub landed in the Blog repo instead, renaming a directory in a repository the command had nothing to do with. One agent moving between two repositories is the same failure as two agents sharing one, so a per-agent rule would have permitted exactly the thing that went wrong.

Worth pairing the rule with a mechanical habit, since the rule alone did not save me: never rely on the inherited working directory for a mutating command. Use an absolute path, or cd <abs> && <cmd> in the same invocation. A read in the wrong directory is a wasted call; a git mv, rm, checkout, or add -A in the wrong directory is damage.

"What an agent does when it finds a foreign checkout anyway." Leave it and clone its own, which is what I eventually did, and the recovery is cheap: git clone, branch, configure signing, push, open the pull request. Roughly a minute against an incident that cost the better part of an hour.

The part the rule should state explicitly is what to do about a footprint already left, because "leave it alone" arrives too late by then. What worked: save the work aside first, git restore only the files I had touched, verify the tree is clean, delete my branch from their clone, and then say plainly what had been touched. Verifying afterwards mattered, since I had also left a regenerated report that looked like theirs and would have been committed by whoever ran the next git add -A.

One more signal worth naming in the rule

A shared checkout announces itself before it bites, and both signals showed here and were noticed too late: a branch that changes when nothing you did changed it, and an edit of yours that is reverted with no conflict. Either one means another agent is live in the tree, and the correct response is to stop and back out rather than re-apply the edit. I re-applied mine, which is the wrong instinct and the one an agent will have by default.

🤖 Generated with Claude Code

[ptr727]

Follow-up evidence for the mechanical half of this, because the rule as I stated it above was not sufficient and I have now watched it fail three times in one session rather than once.

The first two were a git mv and a sed -i run from an inherited working directory. The third is the interesting one, because by then I had already written the rule down and still tripped it: a python3 heredoc whose body opened pathlib.Path("TODO.md"). The shell command carried no path at all, so "use an absolute path for a mutating command" read as satisfied while the mutation lived one layer down, inside the script.

It ran against the wrong repository. The damage was quiet in the way that matters: the script replaced zero occurrences and reported success, but read_text() followed by write_text(newline="\n") normalizes line endings unconditionally, so a CRLF repository quietly became LF in a file the change had nothing to do with. A diff would have shown every line modified. Caught only because I ran git status afterwards out of habit.

Two things worth folding into the rule when it is written, both cheap:

• The path has to be absolute inside the script body, not only on the shell command. A heredoc, a -c argument, and an inline jq -f all inherit the cwd, and all three read as pathless from outside.
• Assert what the edit expects to find. assert n == 3 turns a wrong-directory run into a loud failure. Without it, "replaced 0 occurrences" prints as a success line, which is the same false-clean shape as a suppressed review finding or an unverified wait.

The general form is that an operation which silently no-ops in the wrong place is more dangerous than one that errors, because the agent reads the no-op as done and moves on.

[ptr727]

Complete on the rule and on both open questions, fixed by 9d85941 (#593) and re-verified against develop at a706ddb today.

GOVERNANCE.md "Repository Boundaries and Write Safety" carries the rule that each task runs in its own checkout, in its own directory, on its own feature branch, scoped per task rather than per agent, which adopts the first open question: one agent moving between two repositories meets the same hazard as two agents sharing one tree, so a rule written per agent permits exactly the case that goes wrong.

It names the three commands that cross the boundary while being correct in isolation, a blanket git add -A, a git reset --hard, and a branch switch, and it names the two signals that another task is live in a tree, a branch that changed when nothing you did changed it and an edit of yours reverted with no conflict, whose stated response is to stop rather than to re-apply. That adopts the second open question.

The rule reaches every machine through the same text under host-setup/agent-safety/, which is what covers sessions no repository instruction set reaches.