From b3f986ea5379d35da3ead668bf7dcdfd2dc97208 Mon Sep 17 00:00:00 2001
From: "burrito.space" <me@burrito.space>
Date: Sat, 18 Jul 2026 12:51:07 +0200
Subject: [PATCH] build(clone-pool): relocate pool clones in-repo to
 .worktrees/, pin mobile to sibling

---
 .claude/skills/agent-review/SKILL.md     | 16 ++++++++--------
 .claude/skills/mpeek-clone-pool/SKILL.md | 11 ++++++++---
 .gitignore                               |  2 +-
 scripts/clean-isolated-clone.sh          | 10 +++++++++-
 scripts/finalize-isolated-clone.sh       | 10 +++++++++-
 scripts/reset-isolated-clone.sh          | 10 +++++++++-
 scripts/spawn-isolated-clone.sh          | 13 +++++++++++--
 7 files changed, 55 insertions(+), 17 deletions(-)

diff --git a/.claude/skills/agent-review/SKILL.md b/.claude/skills/agent-review/SKILL.md
index fd9f3027..b137808a 100644
--- a/.claude/skills/agent-review/SKILL.md
+++ b/.claude/skills/agent-review/SKILL.md
@@ -29,8 +29,8 @@ failure mode (see [Failure modes](#failure-modes-name-them-in-the-brief)). The
 real gate is `yarn test:desktop:electron` in the main checkout — not a second LLM read.
 
 Orchestrator review:
-1. `jj -R ../mpeek-clone-<name> diff --stat -r 'main..@'` — scope check.
-2. `jj -R ../mpeek-clone-<name> diff -r 'main..@'` or `Read` each changed file.
+1. `jj -R .worktrees/<name> diff --stat -r 'main..@'` — scope check.
+2. `jj -R .worktrees/<name> diff -r 'main..@'` or `Read` each changed file.
 3. Look for: cross-app touches, missing tests, scope creep, secrets,
    `webSecurity:false` / `sandbox:false` regressions, lazy `require('electron')`,
    `setTimeout` in main without `isDestroyed()` guard, top-level
@@ -41,11 +41,11 @@ Orchestrator review:
 ## Reviewer subagent brief template
 
 ```
-You are reviewing agent-produced work in clone /Users/dietrich/misc/mpeek-clone-<name>/.
+You are reviewing agent-produced work in clone .worktrees/<name>/.
 The agent claims it implemented <task>. Verify the claim — do NOT trust it.
 
 ACCEPTANCE (all runtime, all must pass — no grep shortcuts):
-1. `jj -R ../mpeek-clone-<name> diff --stat -r 'main..@'` — list files; flag any
+1. `jj -R .worktrees/<name> diff --stat -r 'main..@'` — list files; flag any
    touch outside the declared scope.
 2. `yarn workspace @peek/desktop test:unit` from the clone — must pass; report
    numeric count.
@@ -89,8 +89,8 @@ Reviewer subagents drift toward these. Naming them in the brief reduces it.
      a. echo <name> > /tmp/mpeek-agent-name
      b. scripts/finalize-isolated-clone.sh
      c. If FF rejected: rebase IN THE CLONE
-          (jj -R ../mpeek-clone-<name> git fetch --remote origin
-           jj -R ../mpeek-clone-<name> rebase -s 'roots(::@ ~ ::main)' -d main)
+          (jj -R .worktrees/<name> git fetch --remote origin
+           jj -R .worktrees/<name> rebase -s 'roots(::@ ~ ::main)' -d main)
         Then retry finalize.
 3. After ALL targeted clones finalized:
      yarn test:desktop:electron   # run_in_background, FULL suite (all 6 runners, ~3300+, ~10 min), canonical gate
@@ -141,7 +141,7 @@ When `test:desktop:electron` fails after landing:
    ```
    Your <task> landed but yarn test:desktop:electron failed: <paste failing test +
    relevant log lines>. The commit was abandoned from main. The clone at
-   ../mpeek-clone-<name>/ still has your work. Diagnose, fix in the clone,
+   .worktrees/<name>/ still has your work. Diagnose, fix in the clone,
    commit, and report back. Same brief as before re: do-not-finalize,
    do-not-push.
    ```
@@ -161,4 +161,4 @@ its node_modules + jj state; no respawn overhead.
 /agent-review adblocker-resilience
 ```
 
-If no name passed, list clones in the pool (`ls -d ../mpeek-clone-*`) and ask.
+If no name passed, list clones in the pool (`ls -d .worktrees/*`) and ask.
diff --git a/.claude/skills/mpeek-clone-pool/SKILL.md b/.claude/skills/mpeek-clone-pool/SKILL.md
index 94d6c4ab..3ebadfd6 100644
--- a/.claude/skills/mpeek-clone-pool/SKILL.md
+++ b/.claude/skills/mpeek-clone-pool/SKILL.md
@@ -11,7 +11,7 @@ dedicated Electron profile dir so tests don't race on shared DB / ports / window
 state. The `node_modules` for the app(s) in scope are symlinked from the main
 checkout; no `yarn install` needed.
 
-**Pool cap: 5.** Check `ls ../mpeek-clone-*` before spawning a new slot.
+**Pool cap: 5.** Check `ls .worktrees/*` before spawning a new slot.
 
 ```bash
 echo <name> > /tmp/mpeek-agent-name
@@ -20,7 +20,7 @@ echo apps/desktop > /tmp/mpeek-clone-scope      # optional: only that app's node
 echo <task-uuid> > /tmp/mpeek-clone-task        # optional but recommended: Peek task id
 scripts/spawn-isolated-clone.sh
 
-# Inside the clone (you're cd'd into ../mpeek-clone-<name>):
+# Inside the clone (you're cd'd into .worktrees/<name>):
 PROFILE=clone-<name> yarn <script>
 
 # After work is done — rebase commits into main checkout's bookmark.
@@ -37,7 +37,7 @@ Task association (optional, recommended): when `/tmp/mpeek-clone-task` is set,
 spawn records it as `<clonedir>/.clone-task` (gitignored, never tracked), and
 clean echoes it on teardown so you can see which task is being reclaimed.
 Recommended naming: `/tmp/mpeek-agent-name` = `<task-id-prefix>-<short-label>`
-(e.g. `71cfde09-chrome-host-gate`) so `ls ../mpeek-clone-*` is self-documenting.
+(e.g. `71cfde09-chrome-host-gate`) so `ls .worktrees/*` is self-documenting.
 
 Why true clones (not jj workspaces): physically separate `.jj` dirs eliminate
 the concurrent-edit hazard. Integration happens via a registered `pool-<name>`
@@ -71,6 +71,11 @@ Rust `target/` output per ABI plus Xcode derived data + `libapp.a` /
 `PeekCore.xcframework` outputs. Cold rebuild is ~2 min Rust + Xcode time;
 cached is ~15 s.
 
+Unlike pool clones (which now live in-repo at `.worktrees/<name>`), the
+`mobile` slot deliberately stays at the legacy sibling path
+`../mpeek-clone-mobile` — moving it in-repo would orphan its warm ~12GB iOS
+build cache.
+
 ```bash
 scripts/spawn-mobile-workspace.sh    # hard-codes name=mobile, base=main, scope=apps/mobile
 # clone at ../mpeek-clone-mobile/ — PERSISTS across spawns
diff --git a/.gitignore b/.gitignore
index 9c64d6a9..b5c2cbc9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -49,7 +49,7 @@ handoff.md
 # Isolated agent workspaces (created by scripts/spawn-isolated-agent.sh)
 ../mpeek-agent-*
 # Isolated agent clones (created by scripts/spawn-isolated-clone.sh)
-../mpeek-clone-*
+.worktrees/
 # Local clone-task metadata (created by spawn-isolated-clone.sh inside a
 # clone's own root when /tmp/mpeek-clone-task is set — never tracked)
 .clone-task
diff --git a/scripts/clean-isolated-clone.sh b/scripts/clean-isolated-clone.sh
index 3adff1c2..80fc1bb9 100755
--- a/scripts/clean-isolated-clone.sh
+++ b/scripts/clean-isolated-clone.sh
@@ -34,7 +34,15 @@ if [ "$NAME" = "mobile" ] && [ "${MOBILE_FORCE_CLEAN:-}" != "1" ]; then
 fi
 
 MAIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
-CLONE_DIR="${MAIN_DIR}/../mpeek-clone-${NAME}"
+# Pool clones live in-repo at .worktrees/<name>. The `mobile` slot is the one
+# exception: it stays at the legacy sibling path to preserve its warm iOS build
+# cache (~12GB). This is a deliberate bridge — when mobile is next rebuilt from
+# scratch it should move in-repo too and this special case can go.
+if [ "$NAME" = "mobile" ]; then
+  CLONE_DIR="${MAIN_DIR}/../mpeek-clone-${NAME}"
+else
+  CLONE_DIR="${MAIN_DIR}/.worktrees/${NAME}"
+fi
 REMOTE_NAME="pool-${NAME}"
 PROFILE="clone-${NAME}"
 PROFILE_DIR="${HOME}/Library/Application Support/Peek/${PROFILE}"
diff --git a/scripts/finalize-isolated-clone.sh b/scripts/finalize-isolated-clone.sh
index d94c7320..85c38603 100755
--- a/scripts/finalize-isolated-clone.sh
+++ b/scripts/finalize-isolated-clone.sh
@@ -50,7 +50,15 @@ if [ -z "$NAME" ]; then
 fi
 
 MAIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
-CLONE_DIR="${MAIN_DIR}/../mpeek-clone-${NAME}"
+# Pool clones live in-repo at .worktrees/<name>. The `mobile` slot is the one
+# exception: it stays at the legacy sibling path to preserve its warm iOS build
+# cache (~12GB). This is a deliberate bridge — when mobile is next rebuilt from
+# scratch it should move in-repo too and this special case can go.
+if [ "$NAME" = "mobile" ]; then
+  CLONE_DIR="${MAIN_DIR}/../mpeek-clone-${NAME}"
+else
+  CLONE_DIR="${MAIN_DIR}/.worktrees/${NAME}"
+fi
 REMOTE_NAME="pool-${NAME}"
 
 if [ ! -d "$CLONE_DIR" ]; then
diff --git a/scripts/reset-isolated-clone.sh b/scripts/reset-isolated-clone.sh
index 9eb6a584..91c5a689 100755
--- a/scripts/reset-isolated-clone.sh
+++ b/scripts/reset-isolated-clone.sh
@@ -25,7 +25,15 @@ if [ -z "$NAME" ]; then
 fi
 
 MAIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
-CLONE_DIR="${MAIN_DIR}/../mpeek-clone-${NAME}"
+# Pool clones live in-repo at .worktrees/<name>. The `mobile` slot is the one
+# exception: it stays at the legacy sibling path to preserve its warm iOS build
+# cache (~12GB). This is a deliberate bridge — when mobile is next rebuilt from
+# scratch it should move in-repo too and this special case can go.
+if [ "$NAME" = "mobile" ]; then
+  CLONE_DIR="${MAIN_DIR}/../mpeek-clone-${NAME}"
+else
+  CLONE_DIR="${MAIN_DIR}/.worktrees/${NAME}"
+fi
 
 if [ ! -d "$CLONE_DIR" ]; then
   echo "error: clone ${CLONE_DIR} does not exist" >&2
diff --git a/scripts/spawn-isolated-clone.sh b/scripts/spawn-isolated-clone.sh
index 619573ea..52bbfb41 100755
--- a/scripts/spawn-isolated-clone.sh
+++ b/scripts/spawn-isolated-clone.sh
@@ -27,7 +27,7 @@
 # gitignored, never tracked). Recommended so clones stay traceable — see
 # the mpeek-clone-pool skill. Unset = no association recorded.
 #
-# Pool cap: 5. Policy, not enforced. Check `ls ../mpeek-clone-*` before
+# Pool cap: 5. Policy, not enforced. Check `ls .worktrees/*` before
 # adding a new slot.
 #
 # Prints two lines on stdout (other output to stderr):
@@ -90,7 +90,15 @@ if [ -r /tmp/mpeek-clone-task ]; then
 fi
 
 MAIN_DIR="$(cd "$(dirname "$0")/.." && pwd)"
-CLONE_DIR="${MAIN_DIR}/../mpeek-clone-${NAME}"
+# Pool clones live in-repo at .worktrees/<name>. The `mobile` slot is the one
+# exception: it stays at the legacy sibling path to preserve its warm iOS build
+# cache (~12GB). This is a deliberate bridge — when mobile is next rebuilt from
+# scratch it should move in-repo too and this special case can go.
+if [ "$NAME" = "mobile" ]; then
+  CLONE_DIR="${MAIN_DIR}/../mpeek-clone-${NAME}"
+else
+  CLONE_DIR="${MAIN_DIR}/.worktrees/${NAME}"
+fi
 PROFILE="clone-${NAME}"
 PROFILE_DIR="${HOME}/Library/Application Support/Peek/${PROFILE}"
 TIMESTAMP=$(date +%s)
@@ -196,6 +204,7 @@ done < <(find . -name package.json \
   -not -path '*/.claude/*' \
   -not -path '*/out/*' \
   -not -path '*/dist/*' \
+  -not -path './.worktrees/*' \
   -maxdepth 4)
 
 if [ -d "$PROFILE_DIR" ]; then
-- 
2.51.2