Worktrees, verification copies, and scratch output
Disk is shared by every agent session on the machine, and nothing cleans up after a session ends. Anything a task creates outside the tracked tree belongs to that task, and removing it is part of the task.
- Verify in place first. Run checks in the working tree when it reflects
the change under test. When an isolated tree is genuinely needed (a
clean-tree qualification, a mutation run, a comparison between commits), use
git worktree add --detach. Never copy a checkout withcp -R,rsync, or similar: that duplicates installed dependencies and build output, and a worktree starts from tracked files only. - Keep worktrees outside the checkout, in one place per repository, such as
../.worktrees/<repo>/<purpose>next to the clone. A worktree nested inside the checkout is picked up by test discovery, type-checking, file watchers, and search. When a harness manages its own worktree location, use that. - Reuse one worktree per purpose across runs: check out the next commit in it rather than adding a worktree per run, per commit, or per reviewer. When a run needs a pristine tree, clean a worktree this task created rather than creating another. In a worktree you did not create, remove only output you can identify as this task's, and report anything else instead of cleaning it.
- Keep build caches shared, not multiplied. Where this repository's Tooling
guidance (the
AGENTS.mdTooling section or alocal-validation-<type>skill) says where a worktree's dependencies and build output live, follow it; otherwise keep them inside that worktree so they are removed with it. - Put temporary files in the session's scratch directory when the harness
provides one, otherwise in a
mktemp -ddirectory, never at fixed paths in/tmp, in the checkout's parent directory, or in sibling folders next to it. Evidence that must outlive the session belongs where this repository documents it; otherwise summarize it in the report rather than leaving files behind. - Clean up before finishing. Remove the worktrees you added with
git worktree remove, thengit worktree prune, and delete the scratch output you created. Remove only what this task created; report anything else you find rather than deleting it.