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]>

CLAUDE.md

@@ -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*
@@ -87,11 +93,13 @@ Remove yours when you are done:
 
     git worktree remove /path/outside/the/repo/wt-<slug>
 
-Measured 2026-10-05: that command **succeeds** under the agent sandbox (rc 0, on a throwaway
-worktree in the session scratchpad) — earlier sessions recorded it as blocked, and that
-record was wrong, or at least no longer true. Try it; it probably works. If it is refused,
-say so in your handoff and leave the worktree registered — do **not** `rm -rf` the directory,
-which leaves a registered worktree pointing at nothing and still holding the branch.
+Measured 2026-10-05: on a worktree **you created yourself, in the session scratchpad**, that
+command **succeeds** — rc 0, no prompt, with or without a branch checked out. The "worktree
+removal is sandbox-blocked" note in circulation is about the `.claude/worktrees/agent-*` ones
+belonging to *other* sessions, some of which are additionally `locked` on git's own terms. So:
+remove yours, and only yours. If removal is refused, say so in your handoff and leave the
+worktree registered — do **not** `rm -rf` the directory, which leaves a registered worktree
+pointing at nothing and still holding the branch.
 
 If someone *else's* stale worktree is holding the branch you need, do not try to reclaim the
 branch name. Push a `rework/<pr-number>` branch to the PR's refspec instead.

decisions/2026-10-05-agents-work-in-their-own-workspace.md

@@ -55,12 +55,24 @@ 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
-`git worktree list` no longer shows it. §0 therefore tells agents to try it, and the
-`rework/<pr-number>` escape hatch is now scoped to *someone else's* stale worktree holding a
-branch, which is a real and separate problem (31 of them).
+`git worktree list` no longer shows it. §0 therefore tells agents to remove their own, and
+scopes the "blocked" note to what it actually covers: *other* sessions'
+`.claude/worktrees/agent-*`, some of which are additionally `locked` on git's own terms. The
+`rework/<pr-number>` escape hatch is now scoped to someone else's stale worktree holding a
+branch, which is a real and separate problem (31 of them). Both of my own worktrees in this
+session were removed cleanly at rc 0 after pushing.
 
 `spec-immutability` is avoidable-not-tolerated: taken from
 `decisions/2026-10-01-render-selftest-runs-in-gate.md`, which records