fix(#1369): refresh wave manifest and re-check base before each wave in execute-phase (#1492)

* fix(#1369): refresh wave manifest and re-check base before each wave in execute-phase

Two compounding issues caused wave N+1 worktrees to fork from the stale
pre-wave-N commit, immediately tripping the worktree_branch_check FATAL
guard in every executor:

1. worktree.base-check auto-degrade only ran once at initialize time.
   After wave N merges advanced orchestrator HEAD past origin/HEAD, new
   worktrees were still forked from origin/HEAD (Claude Code "fresh" base).

2. WAVE_WORKTREE_MANIFEST was never unset between waves, so wave N+1
   reused the consumed wave-N manifest file, which would have blocked the
   step 5.5 manifest guard (#3384) on subsequent waves.

Fix: add two safeguards in execute-phase.md —
- Step 0.5 (start of each wave): re-runs worktree.base-check; auto-degrades
  USE_WORKTREES=false for that wave when HEAD has diverged from origin/HEAD.
- Step 7c (end of each wave): unsets WAVE_WORKTREE_MANIFEST so wave N+1
  creates a fresh per-wave manifest; re-asserts worktree.set-baseref
  (idempotent) and re-evaluates base degradation after wave merges land.

17 regression tests added in tests/bug-1369-wave-stale-base.test.cjs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(#1369): rename test to fix-NNN convention; update workflow size baseline

Rename tests/bug-1369-wave-stale-base.test.cjs → tests/fix-1369-wave-stale-base.test.cjs
to satisfy the lint-regression-test-names gate (new files cannot use bug-NNN prefix).

Update tests/workflow-size-baseline.json for execute-phase.md: 93157 → 97393
(LF-normalized byte count after adding step 0.5 inter-wave base re-check and
step 7c between-wave manifest reset).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(#1369): add issue reference to allow-test-rule comment

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(#1369): extract new execute-phase steps to references; satisfy ADR-857 cap

Step 0.5 (inter-wave worktree base re-check) and steps 7b–7c (pre-wave
dependency check + between-wave manifest reset/base refresh) added by this
PR grew execute-phase.md to 97393 bytes, violating the ADR-857 phase-6
architectural mandate that host-loop bodies remain strictly below the
pre-phase-6 baseline of 93166 bytes.

Extract both new blocks into dedicated reference files:
- gsd-core/references/execute-phase-wave-guard.md (step 0.5)
- gsd-core/references/execute-phase-between-wave-reset.md (steps 7b + 7c)

Replace inline prose with @-reference pointers. File now measures 92851
bytes (LF-normalized), satisfying the ADR-857 capstone conformance gate.

Also update tests/workflow-size-baseline.json to 92851 and add both new
reference files to docs/INVENTORY-MANIFEST.json.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(#1369): update regression tests to read from extracted reference files

Steps 0.5 and 7b+7c were moved to reference files to satisfy the ADR-857
size cap on execute-phase.md. Tests now check @-reference pointers in the
workflow for ordering and read content assertions from the reference files.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-20 14:22:59 -04:00
committed by GitHub
parent fb24d1c7ea
commit f5276b36b3
7 changed files with 254 additions and 7 deletions

View File

@@ -0,0 +1,43 @@
7b. **Pre-wave dependency check (waves 2+ only):**
Before wave N+1, run `gsd-tools.cjs query verify.key-links {phase_dir}/{plan}-PLAN.md` for each upcoming plan.
If any PRIOR-wave artifact link fails, present:
- `## Cross-Plan Wiring Gap` with plan/link/from/pattern rows
- Options: investigate+fix before continue, or continue with cascade risk
Skip key-links that reference files in the CURRENT (upcoming) wave.
7c. **Between-wave manifest reset and worktree base refresh (waves 2+ only — #1369):**
**REQUIRED before each wave transition when `USE_WORKTREES != "false"` and `RUNTIME = "claude"`.**
Wave N's `WAVE_WORKTREE_MANIFEST` was consumed by `worktree.cleanup-wave` in step 5.5. It must be
unset so wave N+1's step 3 creates a fresh manifest for the new wave's worktrees. Without this,
the wave N+1 manifest guard (step 5.5, #3384) blocks on the stale/empty consumed file.
After wave N merges and tracking commits, the orchestrator HEAD has advanced past the commit the
Claude Code harness may have cached as the worktree fork base at session start. New worktrees
spawned for wave N+1 could fork from the stale pre-wave-N HEAD, causing every executor to trip the
`worktree_branch_check` FATAL guard immediately (symptom: `HEAD is <old-sha>, expected <new-sha>`).
```bash
# Unset per-wave manifest so wave N+1 creates a fresh one (#3384, #1369).
unset WAVE_WORKTREE_MANIFEST
# Between-wave base refresh (#1369): after wave N merges and tracking commits, HEAD has
# advanced. Re-assert worktree.baseRef:"head" (idempotent — no-op if already set) so the
# Claude Code harness re-reads the live HEAD on the next Agent(isolation="worktree") call
# rather than using a cached session-start commit as the fork base.
if [ "$RUNTIME" = "claude" ] && [ "$USE_WORKTREES" != "false" ]; then
gsd_run query worktree.set-baseref 2>/dev/null || true
# Safety re-check: evaluate degradation AFTER the wave N commits. If HEAD has diverged
# from origin/HEAD and baseRef is NOT "head", degrade remaining waves to sequential to
# avoid the base-mismatch FATAL in executor agents.
_BETWEEN_DEGRADE=$(gsd_run query worktree.base-check --pick shouldDegrade 2>/dev/null || echo "false")
if [ "$_BETWEEN_DEGRADE" = "true" ]; then
_DEGRADE_MSG=$(gsd_run query worktree.base-check --pick message 2>/dev/null || true)
[ -n "$_DEGRADE_MSG" ] && printf '%s\n' "$_DEGRADE_MSG" >&2
printf 'Degrading to sequential mode for remaining waves: HEAD advanced past worktree fork base after wave %s merge (#1369).\n' "${N}" >&2
USE_WORKTREES=false
fi
fi
```

View File

@@ -0,0 +1,33 @@
0.5. **Inter-wave worktree base re-check (wave N+1 guard — #1369):**
After Wave N merges and tracking commits advance orchestrator HEAD, Claude Code's
`isolation="worktree"` still forks new worktrees from `origin/HEAD` (the "fresh" base),
not the live HEAD. This means Wave N+1 worktrees would be created from the stale
pre-Wave-N base, causing the `worktree_branch_check` guard inside each executor to halt
immediately with a base-mismatch fatal.
**Run this check at the start of every wave when `USE_WORKTREES != "false"` and
`RUNTIME = "claude"`**, including Wave 1 (where it mirrors the initialize-step check):
```bash
if [ "$RUNTIME" = "claude" ] && [ "${USE_WORKTREES:-true}" != "false" ]; then
_WAVE_DEGRADE=$(gsd_run query worktree.base-check --pick shouldDegrade 2>/dev/null || true)
if [ "$_WAVE_DEGRADE" = "true" ]; then
_WAVE_DEGRADE_MSG=$(gsd_run query worktree.base-check --pick message 2>/dev/null || true)
[ -n "$_WAVE_DEGRADE_MSG" ] && printf '%s\n' "$_WAVE_DEGRADE_MSG" >&2
echo "⚠ [#1369] Worktree fork base diverged from orchestrator HEAD (wave merges advanced HEAD past origin/HEAD). Auto-degrading to sequential mode for this wave to avoid base-mismatch halts." >&2
USE_WORKTREES=false
fi
fi
```
If `shouldDegrade` is `true`, override `USE_WORKTREES=false` for **this wave only** —
all plans in this wave execute sequentially on the main working tree. Later waves re-run
this check and may re-enable worktree isolation if `origin/HEAD` is updated (e.g. via
`git fetch` or `worktree.baseRef:"head"` config).
**To avoid this degrade across all waves:** set `worktree.baseRef:"head"` in
`.claude/settings.local.json` (or run `gsd-tools worktree set-baseref`). This tells
Claude Code to fork from the live HEAD instead of `origin/HEAD`, so each wave's new
worktrees always start from the correct post-merge base. See #683 for the base-ref
configuration detail.

View File

@@ -491,6 +491,8 @@ increases monotonically across waves. `{status}` is `complete` (success),
**For each wave:**
@~/.claude/gsd-core/references/execute-phase-wave-guard.md
1. **Intra-wave files_modified overlap check (BEFORE spawning):**
Before spawning any agents for this wave, inspect the `files_modified` list of all plans
@@ -1038,12 +1040,8 @@ increases monotonically across waves. `{status}` is `complete` (success),
**Step 7.3 — `class == "unknown-failure"`:**
Report failed plan and ask Continue/Stop; continuing may cascade into dependent plan failures.
7b. **Pre-wave dependency check (waves 2+ only):**
Before wave N+1, run `gsd-tools.cjs query verify.key-links {phase_dir}/{plan}-PLAN.md` for each upcoming plan.
If any PRIOR-wave artifact link fails, present:
- `## Cross-Plan Wiring Gap` with plan/link/from/pattern rows
- Options: investigate+fix before continue, or continue with cascade risk
Skip key-links that reference files in the CURRENT (upcoming) wave.
@~/.claude/gsd-core/references/execute-phase-between-wave-reset.md
8. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
9. **Proceed to next wave.**
</step>