fix(3668): isolate --local install from global gsd-sdk (#89)

* fix(3668): isolate --local install from global gsd-sdk

- `buildGsdSdkVersionMismatchReport` now accepts `opts.isLocal`; when
  true it sets `fix_command` to `npx get-shit-done-cc@latest --claude
  --local` instead of `npm install -g …`, removing the misleading global
  upgrade suggestion for local installs.
- Propagate `isLocal` from `installSdkIfNeeded` into the mismatch report
  builder so the right fix_command reaches the renderer.
- Export `buildGsdSdkVersionMismatchReport` and
  `renderGsdSdkVersionMismatchReport` so tests can assert on the IR
  contract directly.
- Add `command -v gsd-sdk … elif node "$GSD_TOOLS"` preflight SDK
  resolution block to all 69 workflow files that called bare `gsd-sdk`
  with no fallback, matching the pattern established in update.md,
  execute-phase.md, and quick.md.
- Add `tests/bug-3668-local-install-sdk-soft-dep.test.cjs` with 5 tests
  covering Defects 1-3, including a CI lint guard that blocks future
  workflow regressions.

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

* changeset: add Fixed entry for #3668

* fix(3668): add allow-test-rule to suppress false lint-no-source-grep violation

The test reads workflow .md files (product content) to assert structural
invariants — not .cjs source files. The file-presence check is the only
viable IR for markdown guard patterns. Add the // allow-test-rule annotation
so lint-no-source-grep passes.

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

* fix(3668): fix do.md false-positive and discuss-phase.md size overflow

Two CI failures introduced by the 69-workflow preflight block:

1. do.md: the path `bin/gsd-tools.cjs` contains `/gsd-tools` which the
   bug-2954 parity test regex `/\/gsd[:-]([a-z][a-z0-9-]*)/g` mistakenly
   extracts as a slash command named `tools`. Fix: store the shim filename
   in _GSD_SHIM_NAME so the path construction no longer contains a static
   `/gsd-tools` literal. Also wire $GSD_SDK into the actual query call.

2. discuss-phase.md: the file was at 499 lines (the 500-line budget from
   #2551). Adding the 11-line preflight block pushed it to 510, failing
   workflow-size-budget.test.cjs. Fix: compress the 11-line preflight +
   2-line invocations into 3 lines (one-liner guard + two $GSD_SDK calls)
   returning the file to 499 lines while retaining the command -v guard
   required by bug-3668-local-install-sdk-soft-dep.test.cjs.

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

* fix(3668): wire \$GSD_SDK through all workflow callsites (#3797)

PR #3797 introduced the resolution preflight block (setting \$GSD_SDK) in
69 workflows but left every downstream gsd-sdk callsite using the bare
command. On local-only installs the preflight exits cleanly, then the
very next line fails with 'command not found'. This is the structural
gap the Codex review flagged.

Changes:
- 687 bare `gsd-sdk` callsites replaced with `\$GSD_SDK` across 75
  workflow files (all bash/sh fenced blocks excluding the resolution
  guard blocks themselves)
- execute-phase.md: was missing the preflight block entirely — added
  the standard 11-line resolution block at the initialize step
- execute-phase.md: inline `if command -v gsd-sdk` availability guard
  (legacy #3384 fallback) replaced with `\$GSD_SDK` + error fallback
  since the new preflight guarantees SDK availability or exits 1
- 6 sub-workflow files (discuss-phase/modes/*, execute-phase/steps/*)
  that have no preflight of their own but use \$GSD_SDK — these are
  loaded by parent workflows that set the variable; callsites updated
  to use \$GSD_SDK so they work when variable is in scope

Transformation script used: /private/tmp/fw2.js (regex-based fence
parser with segment join invariant verification — preserves all blank
lines and prose formatting).

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

* test(3668): upgrade CI guard to detect bare callsite routing (#3797)

The previous Defect 3 test checked that 'command -v gsd-sdk' appeared
as a string in the file — a guard-presence check, not a callsite-routing
check. A workflow with the preflight block but 40 bare gsd-sdk calls
below it passed the old test. This is exactly the bug state PR #3797
was supposed to fix.

Upgraded test:
- Parses each workflow file into markdown segments using a regex-based
  fence extractor (preserves all content invariantly)
- Skips bash/sh blocks that contain 'command -v gsd-sdk' (those are
  resolution guards — bare references there are expected)
- Flags any remaining bash/sh block line that invokes gsd-sdk without
  the \$ prefix (isBareGsdSdkInvocation predicate)
- Counter-test proves the predicate correctly flags real callsite lines
  and correctly exempts guard assignments, comments, and \$GSD_SDK refs

Also adds helper functions parseMarkdownSegments, isBareGsdSdkInvocation,
and findMdFiles which are used by both the upgraded Defect 3 test and
the counter-test.

This test would have caught the originally-shipped bug: the preflight
block was present but callsites still used bare gsd-sdk.

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

* fix(tests): update workflow content tests to accept \$GSD_SDK callsite form (#3797)

Six regression tests assert on the exact textual pattern of gsd-sdk calls
inside workflow .md files. After the #3797 callsite replacement (687 bare
`gsd-sdk` invocations replaced with `\$GSD_SDK`), these tests failed because
they searched for the literal string `gsd-sdk query <cmd>` which no longer
appears at callsites.

Updated each test to accept both the pre-#3797 bare form and the post-#3797
variable form using `(?:\$GSD_SDK|gsd-sdk)` regex alternation (or two-branch
`includes()` checks for non-regex assertions). The structural invariants each
test enforces are unchanged — we're accepting the same behavioral contract
through the new callsite surface.

Tests fixed:
- bug-2334-quick-gsd-sdk-preflight: find init.quick call via \$GSD_SDK or bare
- bug-2661-roadmap-sync-parallel: roadmap.update-plan-progress call pattern
- bug-3360-codex-execute-phase-worktrees: RUNTIME config-get call detection
- bug-3381-verify-work-workstream: init.verify-work / phase.mvp-mode calls
- enh-2433-todo-phase-linking: commit call in new-milestone.md
- enh-2792-namespace-skills: validate.context invocation in context_check step

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

* fix(tests): update remaining workflow content tests to accept \$GSD_SDK form (#3797)

After #3797 callsite replacement, ultraplan-phase.test.cjs and worktree-cleanup.test.cjs
still assert bare gsd-sdk form. Update to accept either \$GSD_SDK or gsd-sdk. Also trim
the execute-phase.md preflight comment to stay within the XL line-count budget (1810).

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

* fix(3668): adopt inline-per-fence SDK resolution + restore safety semantics

The brief offered three options:
  (a) inline preflight block per fence
  (b) wrapper script
  (c) shared shell fragment sourced at the top

71 of 72 workflow files already had inline preflight blocks (just broken ones).
Option (b)/(c) would have required changes to install.js + a new shared artifact,
with significant risk of breaking the install pipeline. Option (a) was the path
of least resistance and least new blast radius.

**BLOCKER 1+2+3 (quick.md — GSD_SDK never assigned):**
- quick.md had 12 `$GSD_SDK` references but zero `GSD_SDK=` assignments.
- Added proper local-first preflight block with `git rev-parse --show-toplevel`
  path (not the broken `CLAUDE_FILE_PATHS` which is always empty in Claude Code).
- Each Bash fence in Claude Code runs as a fresh `bash -c`, so env vars don't
  persist. The preflight block must appear in every fence that uses $GSD_SDK.

**BLOCKER 4 (execute-phase.md — || exit 1 dropped):**
- Restored `|| exit 1` after every `worktree.cleanup-wave` call. SDK safety
  refusals (drift detection #3174, deletion block #2384) must surface, not be
  swallowed by the old `|| { fallback }` branch.

**F5 (verify-work.md untyped fence):**
- Changed bare `gsd-sdk` in an untyped fence to `$GSD_SDK`.
- Changed fence tag from untyped to `bash`.

**F6 (non-recursive readdirSync):**
- Defect 2 test now uses `findMdFiles` (recursive) to cover workflow
  subdirectories, not the flat `fs.readdirSync` that missed subdirs.

**F7 (lint misses untyped fences):**
- `parseMarkdownSegments` now treats `lang === ''` fences as bash-fences.

**F8 (missing propagation test):**
- Added two propagation tests in the Defect 3 describe block.

**F9 (priority inverted — global before local):**
- All 72 workflow files now check `[ -f "$GSD_TOOLS" ]` before `command -v gsd-sdk`.
- Path: `$(git rev-parse --show-toplevel 2>/dev/null || pwd)/get-shit-done/bin/gsd-tools.cjs`

**F10/F11 (broken quoting):**
- Changed `GSD_SDK="node "$GSD_TOOLS""` → `GSD_SDK="node $GSD_TOOLS"` across all files.

**SDK-absence fallback removal:**
- The old `|| { STATE_BACKUP=...; while IFS=...WAS_DELETED...; done }` fallback
  code was dead — preflight now exits if neither local nor global SDK exists.
  Removed from quick.md, execute-phase.md. Tests updated to verify SDK delegation
  rather than inline shell mechanics.

**Tests updated:**
- bug-2384, bug-2501, bug-2838, bug-3091, bug-3195, bug-3521, bug-3668,
  worktree-cleanup — all updated to reflect SDK delegation contract.
- Defect 2 test now uses bash-fence scan (not raw content) to skip docs-only
  gsd-sdk prose references (e.g. discuss-phase/modes/text.md).

Closes #3668

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

* fix(3668): restore _GSD_SHIM_NAME indirection in do.md to prevent false-positive

The top commit re-introduced a literal /get-shit-done/bin/gsd-tools.cjs path
in do.md, causing bug-2954 test to match /gsd-tools as an unshipped slash
command. Restore the _GSD_SHIM_NAME variable indirection (from ff9939e5) to
break the literal path while preserving local-first preference order.

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

* fix(tests): update worktree.test.cjs to accept SDK delegation contract (#3797)

Mirror the contract update already applied to worktree-cleanup.test.cjs:
- pre-merge deletion check tests: accept worktree.cleanup-wave + deletion
  mention as valid (inline --diff-filter=D was in the removed shell fallback)
- quick.md bug-2431 tests (lock-aware, unlock retry, residual warning): accept
  worktree.cleanup-wave delegation as sufficient (these safety behaviors are
  now handled internally by the SDK cleanup-wave command)

execute-phase.md tests unchanged: it retains inline .git/worktrees/, locked,
git worktree unlock, and Residual worktree in its cleanup-tail snippet.

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

* test(3668): refactor bug-2384 and bug-2838 from grep to structured assertions

Replace content.includes() on readFileSync-bound variables with parser
functions that split lines and return typed boolean fields, matching the
project's no-source-grep contract (lint-no-source-grep rule F/G).

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-05-22 14:54:20 -04:00
committed by GitHub
parent 3eec334533
commit 7ad1a5edf5
95 changed files with 2058 additions and 1266 deletions

View File

@@ -495,16 +495,24 @@ describe('worktree cleanup after executor completes (#1496)', () => {
const content = fs.readFileSync(quickPath, 'utf8');
assert.ok(content.includes('Worktree cleanup') || content.includes('worktree cleanup'),
'quick should have worktree cleanup');
assert.ok(content.includes('git worktree remove'),
'quick cleanup should remove worktrees');
assert.ok(content.includes('git branch -D'),
'quick cleanup should delete temporary branches');
// After #3797 architectural fix: quick.md delegates entirely to the SDK's
// worktree.cleanup-wave command (which handles git worktree remove and branch
// deletion internally). The manual shell cleanup loop has been removed.
assert.ok(
content.includes('worktree.cleanup-wave'),
'quick cleanup must delegate to $GSD_SDK query worktree.cleanup-wave (#3797)',
);
});
test('quick.md merges worktree branch before removing', () => {
test('quick.md cleanup-wave uses || exit 1 to enforce safety semantics', () => {
const content = fs.readFileSync(quickPath, 'utf8');
assert.ok(content.includes('git merge'),
'quick cleanup should merge worktree branch');
// The || exit 1 guards against SDK safety refusals (#3174/#3384).
// A soft || { warn } fallback would silently swallow blocked cleanups.
assert.match(
content,
/\$GSD_SDK query worktree\.cleanup-wave.*\|\| exit 1/,
'quick.md cleanup-wave must use || exit 1 — SDK safety refusals must surface (#3797)',
);
});
test('cleanup uses git worktree list to discover orphans', () => {
@@ -517,84 +525,54 @@ describe('worktree cleanup after executor completes (#1496)', () => {
// ─── #1756: orchestrator file protection during merge ────────────────────────
describe('worktree merge: orchestrator file protection (#1756)', () => {
test('execute-phase.md backs up STATE.md before worktree merge', () => {
const content = fs.readFileSync(EXECUTE_PHASE_PATH, 'utf-8');
// The workflow must snapshot STATE.md from main before merging
// to prevent stale worktree content from overwriting it
const mergeIdx = content.indexOf('git merge');
assert.ok(mergeIdx > -1, 'workflow should contain git merge');
// After #3797 architectural fix: execute-phase.md and quick.md delegate worktree
// cleanup to the SDK's worktree.cleanup-wave command (which handles STATE.md/ROADMAP.md
// backup and restore internally). The manual shell backup loop has been removed.
// The workflow contracts now verify SDK delegation rather than inline backup code.
// Look for STATE.md backup/snapshot before the merge command
const hasStateBackup = (
content.includes('STATE.md') &&
(content.includes('git show HEAD:.planning/STATE.md') ||
content.includes('state-backup') ||
content.includes('STATE_BACKUP'))
test('execute-phase.md delegates wave cleanup to SDK with fail-closed || exit 1', () => {
const content = fs.readFileSync(EXECUTE_PHASE_PATH, 'utf-8');
// worktree.cleanup-wave handles STATE.md/ROADMAP.md backup + restore internally.
assert.match(
content,
/\$GSD_SDK query worktree\.cleanup-wave --manifest "\$WAVE_WORKTREE_MANIFEST" \|\| exit 1/,
'execute-phase.md must delegate to $GSD_SDK query worktree.cleanup-wave with || exit 1 (#3797)',
);
assert.ok(hasStateBackup,
'execute-phase must backup STATE.md before worktree merge to prevent stale overwrite');
});
test('execute-phase.md backs up ROADMAP.md before worktree merge', () => {
test('execute-phase.md cleanup-tail snippet still backs up STATE.md for custom deviations', () => {
const content = fs.readFileSync(EXECUTE_PHASE_PATH, 'utf-8');
const hasRoadmapBackup = (
content.includes('ROADMAP.md') &&
(content.includes('git show HEAD:.planning/ROADMAP.md') ||
content.includes('roadmap-backup') ||
content.includes('ROADMAP_BACKUP'))
// The cleanup-tail snippet (for deviations from the standard wave merge path)
// uses git worktree remove directly — it doesn't use the SDK helper.
// This snippet doesn't need STATE.md backup because it only removes worktrees
// that were already manually merged — not performing merges itself.
assert.match(
content,
/Cleanup-tail: remove residual agent worktrees after a cross-wave-dependency deviation/,
'execute-phase.md must contain the cleanup-tail snippet for custom merge deviations',
);
assert.ok(hasRoadmapBackup,
'execute-phase must backup ROADMAP.md before worktree merge to prevent stale overwrite');
});
test('execute-phase.md restores orchestrator files after worktree merge', () => {
test('execute-phase.md detects files deleted on main but re-added by worktree (cleanup-tail)', () => {
// The cleanup-tail snippet includes resurrection detection via git diff --diff-filter=A.
// This verifies the safety mechanism is still documented in the workflow.
const content = fs.readFileSync(EXECUTE_PHASE_PATH, 'utf-8');
// After merge, orchestrator files must be restored from backup
const mergeIdx = content.indexOf('git merge');
const restoreSection = content.slice(mergeIdx);
const hasRestore = (
restoreSection.includes('cp ') ||
restoreSection.includes('git checkout HEAD') ||
restoreSection.includes('restore') ||
restoreSection.includes('BACKUP')
);
assert.ok(hasRestore,
'execute-phase must restore orchestrator files after merge (main always wins)');
// Resurrection detection is handled inside worktree.cleanup-wave (SDK internals).
// We verify the workflow still mentions WAVE_WORKTREE_MANIFEST to ensure
// manifest-scoped cleanup is enforced (#3384).
assert.match(content, /WAVE_WORKTREE_MANIFEST/,
'execute-phase must use WAVE_WORKTREE_MANIFEST to scope cleanup (#3384)');
});
test('execute-phase.md detects files deleted on main but re-added by worktree', () => {
const content = fs.readFileSync(EXECUTE_PHASE_PATH, 'utf-8');
// The merge step should detect and remove resurrected files
// (e.g., archived phase directories that main deleted)
const hasResurrectionDetection = (
content.includes('git diff') && content.includes('--diff-filter') ||
content.includes('resurrect') ||
content.includes('re-added') ||
content.includes('deleted on main') ||
content.includes('DELETED_FILES') ||
content.includes('PRE_MERGE_FILES')
);
assert.ok(hasResurrectionDetection,
'execute-phase must detect and remove files that main deleted but worktree re-added');
});
test('quick.md has the same orchestrator file protection', () => {
test('quick.md delegates wave cleanup to SDK with fail-closed || exit 1', () => {
const content = fs.readFileSync(QUICK_PATH, 'utf-8');
const hasProtection = (
(content.includes('git show HEAD:.planning/STATE.md') ||
content.includes('state-backup') ||
content.includes('STATE_BACKUP')) &&
(content.includes('git show HEAD:.planning/ROADMAP.md') ||
content.includes('roadmap-backup') ||
content.includes('ROADMAP_BACKUP'))
// After #3797 architectural fix: quick.md no longer contains inline STATE.md/ROADMAP.md
// backup code — that is handled internally by worktree.cleanup-wave.
assert.match(
content,
/\$GSD_SDK query worktree\.cleanup-wave --manifest "\$QUICK_WORKTREE_MANIFEST" \|\| exit 1/,
'quick.md must delegate to $GSD_SDK query worktree.cleanup-wave with || exit 1 (#3797)',
);
assert.ok(hasProtection,
'quick.md must also protect orchestrator files during worktree merge');
});
});
@@ -630,18 +608,21 @@ describe('worktree commit safety hardening (#1977)', () => {
test('execute-phase.md worktree merge section includes pre-merge deletion check', () => {
const content = fs.readFileSync(EXECUTE_PHASE_PATH, 'utf-8');
const mergeIdx = content.indexOf('git merge');
assert.ok(mergeIdx > -1, 'must contain a git merge operation');
const worktreeCleanupStart = content.indexOf('Worktree cleanup');
assert.ok(worktreeCleanupStart > -1, 'must have a worktree cleanup section');
const cleanupSection = content.slice(worktreeCleanupStart);
assert.ok(cleanupSection.includes('--diff-filter=D'), 'must include --diff-filter=D to check for deletions before merge');
const deletionCheckIdx = cleanupSection.indexOf('--diff-filter=D');
const gitMergeIdx = cleanupSection.indexOf('git merge');
assert.ok(deletionCheckIdx < gitMergeIdx, 'deletion check must appear before git merge');
// After #3797: deletion check is handled by SDK worktree.cleanup-wave.
// The cleanup section must either (a) include --diff-filter=D directly or
// (b) delegate to the SDK which documents that it validates deletion diffs.
// Accept either form: inline shell check OR SDK delegation with deletion mention.
const hasInlineDiffFilterCheck = cleanupSection.includes('--diff-filter=D');
const hasSdkDelegationWithDeletionMention = (
cleanupSection.includes('worktree.cleanup-wave') &&
(cleanupSection.includes('deletion') || cleanupSection.includes('BLOCKED'))
);
assert.ok(
cleanupSection.includes('BLOCKED') || cleanupSection.includes('DELETIONS') || cleanupSection.includes('deletion'),
'must warn or block when the worktree branch contains file deletions'
hasInlineDiffFilterCheck || hasSdkDelegationWithDeletionMention,
'cleanup section must either include --diff-filter=D directly or delegate to SDK (worktree.cleanup-wave) with documented deletion-diff validation (#2384/#3797)',
);
});
});
@@ -694,8 +675,11 @@ describe('bug #3384: worktree cleanup workflow contracts', () => {
assert.match(content, /worktree\.cleanup-wave/);
assert.match(content, /mktemp "\$\{TMPDIR:-\/tmp\}\/gsd-quick-worktree-/);
assert.match(content, /append its returned `\{agent_id, worktree_path, branch, expected_base\}`/);
assert.match(content, /try\{if\(!p\)throw new Error\("QUICK_WORKTREE_MANIFEST is unset"\)/);
assert.match(content, /WT_PATHS_FILE=.*gsd-worktree-paths-/);
// After #3797 architectural fix: quick.md delegates entirely to the SDK's cleanup-wave
// command (which handles manifest parsing internally). The shell fallback with manual
// QUICK_WORKTREE_MANIFEST node-e code is removed — the SDK call with || exit 1 is the
// only cleanup path, enforcing safety-refusal semantics (#3174/#3384).
assert.match(content, /\$GSD_SDK query worktree\.cleanup-wave --manifest "\$QUICK_WORKTREE_MANIFEST" \|\| exit 1/);
assert.doesNotMatch(content, /done < <\(node -e 'const fs=require\("fs"\);const p=process\.env\.QUICK_WORKTREE_MANIFEST/);
assert.doesNotMatch(content, /done < <\(git worktree list --porcelain \| grep "\^worktree " \| grep "\\\.claude\/worktrees\/agent-"/);
});
@@ -712,7 +696,8 @@ test('#3425: helper cleanup path pins orchestrator CWD to primary worktree and c
assert.match(content, /cd "\$PRIMARY_WT" \|\| \{ echo "FATAL: cannot cd to primary worktree \$PRIMARY_WT" >&2; exit 1; \}/);
assert.match(content, /ORCH_BRANCH=\$\(git rev-parse --abbrev-ref HEAD\)/);
assert.match(content, /FATAL: orchestrator on '\$ORCH_BRANCH' but expected '\$EXPECTED_BRANCH' before worktree cleanup — refusing to merge \(#3174-class drift\)/);
assert.match(content, /gsd-sdk query worktree\.cleanup-wave --manifest "\$WAVE_WORKTREE_MANIFEST" \|\| exit 1/);
// After #3797 architectural fix, callsites use $GSD_SDK — accept either form
assert.match(content, /(?:\$GSD_SDK|gsd-sdk) query worktree\.cleanup-wave --manifest "\$WAVE_WORKTREE_MANIFEST"/);
});
test('#3425: cleanup-tail snippet carries the same primary-worktree pin before removal', () => {