fix(#2772): only disable worktree isolation when planned paths touch submodules (#2779)

* fix(#2772): only disable worktree isolation when planned paths touch submodules

The previous guard in execute-phase.md and quick.md unconditionally set
USE_WORKTREES=false whenever .gitmodules existed, penalising every plan in
a submodule project even when no plan touched a submodule path.

Replace with submodule-path parsing + per-plan path intersection:

- Parse SUBMODULE_PATHS once from .gitmodules via
  `git config --file .gitmodules --get-regexp '^submodule\..*\.path$'`.
- In execute-phase.md, intersect SUBMODULE_PATHS with each plan's
  files_modified frontmatter; disable worktree isolation only for plans
  with non-empty intersection. Fall back to safe-disable for that plan
  when files_modified is missing/unparseable, with a log line explaining
  why.
- In quick.md (no pre-declared paths), keep submodule-path parsing and
  document a fail-loud commit-time guard so the executor aborts only when
  it actually stages a submodule path.

Add tests/bug-2772-gitmodules-path-intersection.test.cjs covering both
files: no unconditional disable, submodule paths are parsed, intersection
logic exists in execute-phase, fallback path is documented.

Full suite: 5680 / 5680 pass.

Closes #2772

* test(#2772): replace source-grep with behavioral test of submodule path intersection

* fix(#2772): wire USE_WORKTREES_FOR_PLAN into dispatch + fix glob matcher + add quick.md commit guard

Address CodeRabbit review on PR #2779 — the original fix computed
USE_WORKTREES_FOR_PLAN but never read it, so the per-plan submodule
intersection was dead code. Dispatch sites still branched on the
project-level USE_WORKTREES.

Changes:

1. execute-phase.md (CRITICAL — dispatch wiring): Move per-plan
   computation into execute_waves as sub-step 2.5, run it for each plan
   before its dispatch, and gate all four dispatch sites on
   USE_WORKTREES_FOR_PLAN: worktree-mode header, sequential-mode header,
   "worktrees disabled" sequential rule, and post-wave cleanup. Document
   PLAN_FILES extraction via jq from the phase-plan-index JSON. Track
   WAVE_WORKTREE_PLANS so post-wave cleanup only runs when at least one
   plan in the wave actually used worktrees.

2. Per-plan gate matcher (MAJOR — glob safety): Strip leading "./" and
   trailing "/" from both submodule and planned paths. Match
   bidirectionally (pf inside sm AND sm inside pf). Handle globby
   planned paths like "vendor/**/*.c" by extracting the literal prefix
   before the first glob metachar and re-checking. Wrap the iteration
   in set -f / set +f so glob expansion does not corrupt patterns.
   Extracted the gate (~92 lines) into
   workflows/execute-phase/steps/per-plan-worktree-gate.md to keep
   execute-phase.md under the 1700-line XL budget.

3. quick.md (CRITICAL — fail-loud guard): Inject SUBMODULE_PATHS into
   the executor Task prompt and add a <submodule_commit_guard> bash
   block the executor must run before every git commit. The guard
   inspects staged paths via `git diff --cached --name-only`, normalizes
   paths, and aborts with a clear ABORT message + recovery instruction
   ("re-run with workflow.use_worktrees=false") when any staged path
   falls inside a submodule.

4. tests/bug-2772-gitmodules-path-intersection.test.cjs: 25 tests total.
   Updated GATE_SNIPPET to match the new bash matcher. Added
   normalization tests (./ prefix, trailing /, glob "vendor/**/*.c",
   parent directory, ./ in .gitmodules). Added workflow-markdown
   wiring assertions for all 4 dispatch sites + per-plan gate file
   extraction. Added quick.md guard tests: prompt injection assertion +
   behavioral fixture-repo tests that stage a submodule path and assert
   the guard exits non-zero with the ABORT message.

Test count: 5701 pass / 0 fail (was 5698/1 before).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-04-27 12:31:32 -04:00
committed by GitHub
parent 77d929429f
commit 8b6c44433f
4 changed files with 729 additions and 15 deletions

View File

@@ -0,0 +1,94 @@
# Per-plan worktree decision (#2772)
Run this for **each plan in the current wave** before its `Task()` dispatch. The output `USE_WORKTREES_FOR_PLAN` gates the dispatch branch (worktree mode vs sequential mode) for that plan only — other plans in the same wave can still take the worktree path.
`SUBMODULE_PATHS` is computed once in the `initialize` step (parsed from `.gitmodules`).
`PLAN_FILES` is the whitespace-separated list of paths the plan declared it will touch, extracted from the `phase-plan-index` JSON loaded in `discover_and_group_plans`:
```bash
# plan_json is the JSON object for this plan from PLAN_INDEX.plans[]
# files_modified is an array of strings (repo-relative paths or globs)
PLAN_FILES=$(jq -r '.files_modified // [] | join(" ")' <<<"$plan_json")
plan_id=$(jq -r '.id' <<<"$plan_json")
```
Then run the per-plan gate:
```bash
USE_WORKTREES_FOR_PLAN="$USE_WORKTREES"
if [ -n "$SUBMODULE_PATHS" ] && [ "$USE_WORKTREES_FOR_PLAN" != "false" ]; then
if [ -z "$PLAN_FILES" ]; then
# Fallback: planned paths are unknown/unparseable — fall back to the safe
# behavior (disable worktree isolation for this plan) and log why.
echo "[worktree] Plan ${plan_id}: files_modified missing/unparseable — disabling worktree isolation as a safety fallback (submodule project)"
USE_WORKTREES_FOR_PLAN=false
else
# Compute intersection with glob-safe normalization. Both sides are
# normalized (strip leading "./", strip trailing "/") and matched
# bidirectionally so a globby planned path like "vendor/**/*.c" still
# matches submodule "vendor/foo", and "./vendor/foo/bar.c" matches
# submodule "vendor/foo".
INTERSECT=""
set -f # disable globbing while iterating literal patterns
for sm_raw in $SUBMODULE_PATHS; do
# Normalize submodule path: strip ./ prefix and trailing /
sm="${sm_raw#./}"
sm="${sm%/}"
[ -z "$sm" ] && continue
for pf_raw in $PLAN_FILES; do
# Normalize planned path the same way
pf="${pf_raw#./}"
pf="${pf%/}"
[ -z "$pf" ] && continue
matched=0
# Direction 1: planned path is the submodule or lies inside it
case "$pf" in
"$sm"|"$sm"/*) matched=1 ;;
esac
# Direction 2: submodule lies inside the planned path (e.g. plan
# declares "vendor" or a glob expanding to a directory containing
# the submodule).
if [ "$matched" -eq 0 ]; then
case "$sm" in
"$pf"|"$pf"/*) matched=1 ;;
esac
fi
# Direction 3: planned path uses a glob — strip glob wildcards
# and check whether the resulting prefix overlaps the submodule
# path in either direction.
if [ "$matched" -eq 0 ]; then
case "$pf" in
*'*'*|*'?'*|*'['*)
# Take the literal prefix before the first glob metachar.
prefix="${pf%%[*?[]*}"
prefix="${prefix%/}"
if [ -n "$prefix" ]; then
case "$sm" in
"$prefix"|"$prefix"/*) matched=1 ;;
esac
if [ "$matched" -eq 0 ]; then
case "$prefix" in
"$sm"|"$sm"/*) matched=1 ;;
esac
fi
fi
;;
esac
fi
if [ "$matched" -eq 1 ]; then
INTERSECT="$INTERSECT $pf_raw"
fi
done
done
set +f
if [ -n "$INTERSECT" ]; then
echo "[worktree] Plan ${plan_id}: planned paths intersect submodule paths (${INTERSECT# }) — disabling worktree isolation for this plan"
USE_WORKTREES_FOR_PLAN=false
fi
fi
fi
```
After running this for the plan, the dispatch branches in `execute_waves` step 3 MUST gate on `USE_WORKTREES_FOR_PLAN` for the current plan, not on the project-level `USE_WORKTREES`. Track which plans in this wave actually used worktrees (append `plan_id` to a `WAVE_WORKTREE_PLANS` accumulator when `USE_WORKTREES_FOR_PLAN != false`) — the post-wave cleanup step (5.5) uses this to decide whether worktree-merge cleanup is needed at all.