---
name: worktree-target-junction
description: "Junction a doc/gate worktree's target onto .worktrees/gate-target instead of setting CARGO_TARGET_DIR — the redirect breaks xtask's hardcoded path, and a fresh target dir costs ~7 GB."
metadata: 
  node_type: memory
  type: feedback
  originSessionId: 1e04b29b-8d37-4b38-84c9-cc0e18fa51e1
  modified: 2026-08-02T04:02:10.760Z
---

For work in a `.worktrees/<name>` worktree that must run `xtask check` (the docs-drift gate), give the worktree a `target` **junction** onto the shared warm cache rather than redirecting the env var:

```powershell
New-Item -ItemType Junction -Path "<worktree>\target" -Target "C:\Users\decid\Documents\projects\spt-core\.worktrees\gate-target"
```

**Why not `CARGO_TARGET_DIR`:** xtask's `spt_bin()` builds via cargo (which honors the var) but returns a hardcoded `<root>/target/debug/spt`, so under a redirect the gate fails NotFound — that is `REQ-XTASK-SPT-BIN-TARGET-DIR`, still unfixed. Junctioning satisfies both: cargo and xtask agree on one path, and the warm cache means a docs-only change gates in seconds instead of a full build.

**Why not a fresh target dir:** ~7 GB per worktree; `.worktrees/gate-target` was 16 GB with the box at 56 GB free. See [[free-space-floor-blocks-golden]].

**Teardown order matters:** delete the junction FIRST (`(Get-Item $p -Force).Delete()` after checking `.LinkType -eq 'Junction'`), then `git worktree remove`. Removal reports `Permission denied` but still deregisters and empties the dir — finish with `git worktree prune` and remove the empty husk. Verify the shared cache survived.

**False-green caveat (2026-08-01, todlando's W3 lane):** a shared gate-target serving MULTIPLE worktrees can hand a lane a STALE test binary built from a foreign tree — green in <1s, count from the wrong sha, `cargo check` green the whole time (check and build keep separate fingerprints). Gate recipe amendment: `cargo clean -p <wave-touched crates>` before lanes in the gate rig, then require a `Compiling` line for each and a test COUNT matching an independently predicted value. See [[shared-target-stale-false-green]].

**Inbound links are the OTHER teardown question (hertz, v0.51.0 reclaim):** deleting a REAL target dir orphans every junction aimed at it, and the refusal-sweep that proves the dir is real does not enumerate its inbound links — doorbell-w5/target junctioned onto doorbell-w4/target (not gate-target!), so reaping w4's real tree left w5 writing through a dead reparse point: cargo fails on a path error that reads as a broken toolchain, not a missing target. Two different checks, run both: outbound (am I about to follow a link?) before recursive deletes, inbound (does anything point at this?) before deleting a real target — `Get-ChildItem .worktrees -Directory | % { Get-Item "$($_.FullName)\target" -Force -EA SilentlyContinue } | ? LinkType | ? Target -like "*<victim>*"`. Never assume a lane's junction aims at gate-target; read its Target.

Related: [[live-agents-lock-target-debug-spt-exe]] (the CARGO_TARGET_DIR redirect advice there is for e2e runs, not for xtask gates), [[spt-verification-gates]], [[scratchpad-target-trees-eat-the-box]].