fix(guard): inspect checkout placement operands

Classify git clone and worktree add operands so HOME-valued environment assignments, sources, references, templates, and metadata do not impersonate checkout destinations. Preserve both forms of clone --separate-git-dir as real placement targets and distinguish shell words, command boundaries, and redirections in the existing quote-aware normalized stream. Deliberate fail-closed residual: unknown future Git options with a separate following word are not adjudicated as source-only. Their value remains a possible placement, so a HOME-shaped value blocks rather than silently creating a bypass. Relative destinations whose effective path depends on cwd remain out of scope in #1197.
2026-08-13 05:55:33 -05:00
parent 20d86e392b
commit 91cc37bcf6
3 changed files with 187 additions and 8 deletions
@@ -0,0 +1,30 @@
+# #1174 — Wrapper guard round 10
+
+## Objective
+
+Make checkout enforcement judge Git placement operands rather than every HOME-shaped word in the command, without reopening `--separate-git-dir` placement under HOME.
+
+## Plan
+
+1. Reproduce the four over-blocks and the placement-option control at head `20d86e39`.
+2. Add RED fixtures before production changes.
+3. Extract clone/worktree placement operands from the existing shell-aware normalized stream.
+4. Run the full guard corpus, historical-head discrimination, syntax/static checks, probes, review, and CI.
+
+## Progress and evidence
+
+- Reproduced: `NOTE=$HOME`, `--reference=$HOME`, `GIT_DIR=$HOME/x`, and `--template=$HOME/t` all blocked despite explicit `/src/wt` destinations.
+- RED at `20d86e39`: expanded suite had 8 failures, all HOME-valued non-placement cases.
+- GREEN: expanded suite passes 242/242.
+- Round-10 probes: 7/7 placement expectations and 4/4 placement-option controls pass.
+- Earlier path probes remain green: 60/60, 24/24, and 17/17.
+- Historical discrimination with the 242-fixture suite:
+  - `3d0a882a`: 216 pass / 26 fail.
+  - `4b8eba95`: 222 pass / 20 fail.
+  - `20d86e39`: 234 pass / 8 fail.
+- `bash -n`, ShellCheck warning-or-higher, and `git diff --check`: pass.
+
+## Residual / risk
+
+- Relative destinations whose effective path depends on cwd are tracked separately by #1197 and remain out of scope.
+- Unknown future Git options with a separate following value fail closed when that value is HOME-shaped. This may require classification when Git adds an unrelated path-taking option, but prevents a new placement option from silently bypassing the guard.