fix(#683): auto-degrade phase execution to sequential on worktree base mismatch (#749)

* fix(#683): auto-degrade phase execution to sequential on worktree base mismatch

Claude Code forks worktree-isolated executors off the repository default
branch (origin/HEAD), not the orchestrator's HEAD. Running /gsd-execute-phase
on a branch diverged from the default (unmerged milestone/feature branch) left
every executor without the phase's plan files and tripped the
worktree-branch-check guard with `exit 42` — 100% reproducible, all OSes.

- New module src/worktree-base-ref.cts: HEAD-vs-fork-base drift detection
  (origin/HEAD with symbolic-ref fallback) and no-clobber worktree.baseRef
  management, exposed as `worktree base-check` / `worktree set-baseref`.
- execute-phase.md: pre-dispatch, for Claude Code with worktrees enabled,
  auto-degrades the run to sequential on the main tree when a base mismatch
  is detected, recommending worktree.baseRef:"head". The exit-42 guard stays
  as a backstop.
- Installer: fresh local Claude installs set worktree.baseRef:"head" in
  .claude/settings.local.json (no-clobber, respecting an explicit shared
  settings.json value); upgrades print an opt-in notice pointing at
  `gsd-tools worktree set-baseref`.
- Docs: how-to guide, CLI/config reference, planning-config cross-ref.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#683): auto-apply worktree.baseRef on upgrade; gate fresh+upgrade on use_worktrees

Per maintainer direction: on a local Claude Code UPGRADE, set
worktree.baseRef:"head" automatically (no opt-in notice) when the project's
workflow.use_worktrees is enabled, instead of merely printing a remediation
notice. For consistency the FRESH path is now gated the same way: both paths
compute worktrees-enabled once (bounded walk-up read of .planning/config.json,
default enabled unless workflow.use_worktrees === false) and apply the
no-clobber baseRef only when enabled — never overwriting an explicit value in
settings.local.json or a shared settings.json. gsd-tools worktree set-baseref
remains for manual use. Docs + changeset updated; tests hardened (file-exists
assertions, fresh+disabled case, upgrade idempotency).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#683): measure workflow byte-budget on LF, fixing Windows-only CI failure

The workflow-size-budget test failed only on Windows: git checks out the .md
files as CRLF (no eol=lf in .gitattributes) and byteCount used
fs.statSync().size (raw on-disk bytes), counting an extra \r per line. That
inflated execute-phase.md — the XL high-water-mark file pinned near its ceiling
by the tighten-only ratchet — from 88492 LF bytes to ~90245 on Windows, over
the 90000 XL ceiling, while passing on the LF-checkout Mac/Linux runners.

The ceilings are explicitly "calibrated against raw `wc -c`" on an LF checkout,
so the measurement should be LF-based on every platform. byteCount now reads the
file and counts Buffer.byteLength after stripping CR, making the budget
platform-independent (a no-op on LF checkouts; verified statSync === normalized
for all 88 workflow files). No ceilings changed. Added a regression test
asserting CRLF and LF content of the same file count identically.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(#683): make worktree-base-ref test path mocks Windows-safe (path.join)

tests/worktree-base-ref.test.cjs keyed its injected readFile/writeFile mocks
(and a few expected `file` values) with forward-slash template literals like
`${claudeDir}/settings.local.json`. The module composes those paths with
path.join(), which emits backslashes on Windows, so the mock keys never matched
the module's lookup → readFile returned null → resolveEffectiveBaseRef /
cmdWorktreeBaseCheck / cmdWorktreeSetBaseRef (and the JSONC variants) failed on
the Windows full-test runner only (they passed on Mac/Linux, and the install
tests passed because they use the real filesystem). The module is correct;
only the test fixtures hardcoded '/'.

All mock keys and path assertions now use path.join(base, ...) mirroring the
module, so they match on every platform (no-op on POSIX). 19 path references
across 16 lines.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-06 23:40:24 -04:00
committed by GitHub
parent edd3c6c332
commit cf8bd3cd5e
18 changed files with 2077 additions and 9 deletions

View File

@@ -64,8 +64,10 @@
const { test, describe } = require('node:test');
const assert = require('node:assert/strict');
const fs = require('fs');
const os = require('node:os');
const path = require('path');
const { assertTightCeiling } = require('../scripts/lib/allowlist-ratchet.cjs');
const { cleanup } = require('./helpers.cjs');
const WORKFLOWS_DIR = path.join(__dirname, '..', 'gsd-core', 'workflows');
@@ -121,10 +123,16 @@ function budgetFor(workflow) {
}
function byteCount(filePath) {
// Match `wc -c`: count every byte on disk, including any trailing newline.
// Deliberately NOT the trailing-newline-stripping logic the old lineCount()
// used — the byte ceilings are calibrated against raw `wc -c` output.
return fs.statSync(filePath).size;
// Count bytes as on an LF checkout, so the budget is platform-independent.
// The tier ceilings are calibrated against `wc -c` on a Unix (LF) checkout,
// but these .md files have no `eol=lf` in .gitattributes, so Windows checks
// them out as CRLF. Counting raw on-disk bytes there adds one byte per line,
// which fails CI on the high-water-mark file (execute-phase.md) on Windows
// ONLY — a false positive that diverges from the LF calibration basis (#683).
// Stripping CR yields the same LF byte count on every platform. Still a raw
// byte count (not the old trailing-newline-stripping lineCount()).
const content = fs.readFileSync(filePath, 'utf-8');
return Buffer.byteLength(content.replace(/\r\n/g, '\n'), 'utf-8');
}
describe('SIZE: workflow byte-size budget', () => {
@@ -549,3 +557,28 @@ describe('workflow progressive disclosure — MVP bodies lazy-loaded (#720)', ()
);
});
});
describe('SIZE: byteCount is line-ending independent (#683 regression)', () => {
// The budget ceilings are calibrated against an LF (Unix) checkout; Windows
// checks these .md files out as CRLF, which previously inflated the count by
// one byte per line and failed CI only on Windows for the high-water file.
test('CRLF and LF content of the same logical file count identically', () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-size-eol-'));
try {
const body = 'line one\nline two\nthree — with a multibyte dash\n';
const lfPath = path.join(dir, 'lf.md');
const crlfPath = path.join(dir, 'crlf.md');
fs.writeFileSync(lfPath, body);
fs.writeFileSync(crlfPath, body.replace(/\n/g, '\r\n'));
assert.strictEqual(
byteCount(crlfPath),
byteCount(lfPath),
'byteCount must normalize CRLF so the byte budget is platform-independent'
);
// And it must remain a real LF byte count (not stripped/whitespace-trimmed).
assert.strictEqual(byteCount(lfPath), Buffer.byteLength(body, 'utf-8'));
} finally {
cleanup(dir);
}
});
});