docs(agents): one workspace per agent run — the shared checkout is off-limits

Agents have been working in the operator's checkout and clobbering each other. Nothing in the tree told them not to: worktrees appeared in CLAUDE.md only as §3's gate workarounds, and decisions/README.md described worktree isolation as something agents already do rather than as a rule. New CLAUDE.md §0 states the rule, with the commands and an explicit do-not list for the shared checkout. Placed before §1 so every existing §-reference in the repo keeps its meaning. Measured in the shared checkout on 2026-10-05, each row a distinct failure mode: 107 `checkout: moving` reflog entries; sitting on feat/pm-agent-issue-to-pr, not main; two other runs' untracked trees left in it; local main two commits behind origin/main; 42 registered worktrees of which 31 are on already-merged branches; 9 gate scripts carrying a `.claude/` exclusion because an in-tree worktree made find-based discovery count the same manifest up to 18 times. Corrects a claim carried in earlier briefs: `git worktree remove` is NOT blocked by the agent sandbox. Provoked on a throwaway worktree — rc 0. §3 reframed as the normal path and grown from two breakages to three: spec-immutability's skip is avoidable, not merely tolerated, with the spec repo mounted read-only in the same ENGINE shim plus -e SPEC_REPO=/home-network-k3s. CLAUDE.md is a sensitive path, so this PR needs a non-author review or an administrator /approve-override posted as a PR review. Not posted by me: §1 forbids an agent clearing that on its own PR. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
2026-10-05 22:26:44 -05:00
2 changed files with 16 additions and 1 deletions
@@ -53,7 +53,13 @@ Each row is a distinct way the shared checkout damages work:

 - **Dirty tree, foreign files.** Two other runs' uncommitted directories were sitting in
  it. An agent that edits there and runs `git add -A` ships someone else's half-finished
-  work inside its own PR, and the PR's author has no idea what those files are.
+  work inside its own PR, and the PR's author has no idea what those files are. This is not
+  hypothetical and it is not historical: **eleven minutes after those two directories were
+  measured, while this very section was being written, another run committed them** —
+  `5334abe feat(pm-agent): ...`, 1,000+ lines across `infra/agent/`, `clusters/`, `catalog/`
+  and `apps/` — onto the shared checkout's checked-out branch, moving its HEAD under anyone
+  reading it. Had this rule's author been working in that tree rather than in a worktree,
+  that commit and this one would have collided.
 - **Stale base.** Its `main` was two commits behind `origin/main`, so
  `git checkout -b x main` there branches off a tree that is already not what CI will merge
  into — the gate you run locally proves a base nobody else has. Worse, it was not even *on*
@@ -55,6 +55,15 @@ recalled:
 | nested worktrees are a gate hazard | `grep -rl '\.claude' conformance/tests platform/monitoring/tests` | **9** scripts carry an explicit exclusion |
 | the 18× double-count | read `platform/monitoring/tests/run.sh:115-123` | in-tree comment, observed 2026-09-12 |

+**The failure mode was observed live, mid-session, not just reconstructed.** The two untracked
+trees I measured at 22:04 and 22:09 were committed at 22:20 by another run — `5334abe`
+`feat(pm-agent): an in-cluster AI Program Manager...`, 1,000+ lines across `infra/agent/`,
+`clusters/`, `catalog/`, `apps/`, `docs/plans/` and its own `decisions/` entry — onto the shared
+checkout's checked-out branch. Measured after the fact: the shared checkout's HEAD moved
+`22c94ef` → `5334abe` and its working tree went clean between my first `git status` and my last,
+with `git log -1` naming a commit that is not mine. That is §0's "shared HEAD" row happening
+during the session that wrote §0, and it is now cited in the doc.
+
 **A claim of mine was wrong and is corrected in the doc.** I had it recorded that
 `git worktree remove` is blocked by the agent sandbox. Provoked rather than assumed: created
 a throwaway detached worktree in the scratchpad and removed it — **rc 0**, and