chore(#191): retire the gsd-sdk shim — route everything at gsd-tools (#522)

* chore(#191): migrate gsd-sdk query call sites to gsd-tools query

Retiring the gsd-sdk shim. gsd-tools.cjs already accepts `query` as a
meta-prefix (gsd-tools query <command>), so this is a behavior-preserving 1:1
swap across the runtime reference prompts, the graphify hook's commit-detection
gate, and two bin/lib comment/message references.

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

* chore(#191): remove vestigial gsd-sdk shim code from installer + projection

The gsd-sdk shim was already not wired up (no gsd-sdk bin in package.json;
buildWindowsShimTriple had zero call sites). Remove the dead code:
- shell-command-projection.cjs: buildWindowsShimTriple + formatSdkPathDiagnostic
  (+ their now-unused PACKAGE_NAME import) and exports
- install.js: the re-export wrappers + imports, the #3406 stale-standalone-sdk
  detection (detectStaleStandaloneSdk/formatStaleStandaloneSdkWarning + its
  global-install call site), and the exports

Preserved (retained, not gsd-sdk): buildCodexHookWindowsShimIR (#3426) — only
its comments referenced the gsd-sdk pattern; reworded. Also kept the
homePathCoveredByRc 'reopen your shell' branch in maybeSuggestPathExport — its
logic is bin-dir-agnostic, only the message mentioned gsd-sdk; reworded to use
the actual bin dir.

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

* test(#191): update tests for retired gsd-sdk shim

- bug-3441/bug-3442: drop the formatSdkPathDiagnostic / buildWindowsShimTriple
  assertions (functions removed); retained PATH-action + drift-guard tests stay
- bug-505: remove the 'still exported' assertions for detectStaleStandaloneSdk /
  formatStaleStandaloneSdkWarning / the shim contract surface (#505 kept them;
  #191 removes them)
- graphify-auto-update: migrate the hook-dispatch inputs gsd-sdk query commit ->
  gsd-tools query commit to match the migrated commit hook

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

* docs(#191): point active docs at gsd-tools query (gsd-sdk shim retired)

Update the user/agent-facing docs (AGENTS, COMMANDS, CONFIGURATION, USER-GUIDE,
ship-pr-body-sections) that presented gsd-sdk query as a current command to
gsd-tools query. Historical docs (ADRs, PRDs, release notes) left untouched.

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

* docs(#191): correct state.load vs state.json description for gsd-tools query

Adversarial-review (codex) finding: the migrated USER-GUIDE line claimed both
'gsd-tools query state.json' and 'state.load' resolve to the frontmatter-rebuild
handler. Verified they don't — state.load returns the CJS load shape
(config + state_raw + flags), state.json returns the frontmatter shape. Both are
available via gsd-tools query; corrected the text to say so.

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

* chore(#191): add changeset for gsd-sdk shim retirement

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-05-30 19:19:14 -04:00
committed by GitHub
parent 2bc295b32d
commit 0fbe1d899e
25 changed files with 91 additions and 319 deletions

View File

@@ -20,7 +20,7 @@
* Parse code-review flags from an argv array.
*
* The first positional argument (phase number) is ignored by this function —
* phase validation is handled by `gsd-sdk query init.phase-op`.
* phase validation is handled by `gsd-tools query init.phase-op`.
*
* @param {string[]} argv - Array of argument strings, e.g. ['2', '--fix', '--all']
* @returns {CodeReviewFlags}

View File

@@ -2,7 +2,6 @@
const path = require('path');
const fs = require('fs');
const { PACKAGE_NAME } = require('./package-identity.cjs');
// Use non-destructured access so test-time mock.method(childProcess, 'spawnSync')
// can intercept calls from this seam — destructured imports capture references
// at load time and become un-mockable.
@@ -311,56 +310,6 @@ function projectPersistentPathExportActions({ targetDir, platform = process.plat
return { shellActions: projected.shellActions };
}
function buildWindowsShimTriple(shimSrc) {
const shimAbs = path.resolve(shimSrc);
const shimQuoted = JSON.stringify(shimAbs);
const invocation = {
interpreter: 'node',
target: shimAbs,
};
const renderCmd = () =>
'@ECHO OFF\r\n@SETLOCAL\r\n@node ' + shimQuoted + ' %*\r\n';
const renderPs1 = () =>
'#!/usr/bin/env pwsh\n& node ' + shimQuoted + ' $args\nexit $LASTEXITCODE\n';
const renderSh = () =>
'#!/usr/bin/env sh\nexec node ' + shimQuoted + ' "$@"\n';
return {
invocation,
eol: { cmd: '\r\n', ps1: '\n', sh: '\n' },
fileNames: { cmd: 'gsd-sdk.cmd', ps1: 'gsd-sdk.ps1', sh: 'gsd-sdk' },
render: { cmd: renderCmd, ps1: renderPs1, sh: renderSh },
};
}
function formatSdkPathDiagnostic({ shimDir, platform, runDir }) {
const isWin32 = platform === 'win32';
const isNpx = typeof runDir === 'string' &&
(runDir.includes('/_npx/') || runDir.includes('\\_npx\\'));
const shimLocationLine = shimDir ? `Shim written to: ${shimDir}` : '';
const actionLines = [];
let shellActions = [];
if (shimDir) {
const projected = projectPathActionProjection({
mode: 'repair',
targetDir: shimDir,
platform,
});
shellActions = projected.shellActions;
actionLines.push('Add that directory to your PATH and restart your shell.');
actionLines.push(...projected.actionLines);
} else {
actionLines.push('Could not locate a writable PATH directory to install the shim.');
actionLines.push('Install globally to materialize the bin symlink:');
actionLines.push(`npm install -g ${PACKAGE_NAME}`);
}
const npxNoteLines = isNpx
? [
"Note: you're running via npx. For a persistent shim,",
`install globally instead: npm install -g ${PACKAGE_NAME}`,
]
: [];
return { shimLocationLine, actionLines, shellActions, npxNoteLines, isNpx, isWin32 };
}
// ─── Subprocess dispatch ──────────────────────────────────────────────────────
@@ -540,8 +489,6 @@ module.exports = {
projectPathActionProjection,
renderShellActionLines,
projectPersistentPathExportActions,
buildWindowsShimTriple,
formatSdkPathDiagnostic,
execGit,
execNpm,
execTool,

View File

@@ -31,7 +31,7 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
subcommands: ['load', 'complete-phase', ...STATE_SUBCOMMANDS.filter((s) => s !== 'load')],
defaultSubcommand: 'load',
unsupported: {
'add-roadmap-evolution': 'state add-roadmap-evolution is SDK-only. Use: gsd-sdk query state.add-roadmap-evolution ...',
'add-roadmap-evolution': 'state add-roadmap-evolution is SDK-only. Use: gsd-tools query state.add-roadmap-evolution ...',
},
error,
cwd,

View File

@@ -5,7 +5,7 @@ Smart discuss is the autonomous-optimized variant of `gsd-discuss-phase`. It pro
**Inputs:** `PHASE_NUM` from execute_phase. Run init to get phase paths:
```bash
PHASE_STATE=$(gsd-sdk query init.phase-op ${PHASE_NUM})
PHASE_STATE=$(gsd-tools query init.phase-op ${PHASE_NUM})
```
Parse from JSON: `phase_dir`, `phase_slug`, `padded_phase`, `phase_name`.
@@ -94,7 +94,7 @@ Read the 3-5 most relevant files to understand existing patterns.
**Get phase details:**
```bash
DETAIL=$(gsd-sdk query roadmap.get-phase ${PHASE_NUM})
DETAIL=$(gsd-tools query roadmap.get-phase ${PHASE_NUM})
```
Extract `goal`, `requirements`, `success_criteria` from the JSON response.
@@ -266,7 +266,7 @@ Write the file.
**Commit:**
```bash
gsd-sdk query commit "docs(${PADDED_PHASE}): smart discuss context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
gsd-tools query commit "docs(${PADDED_PHASE}): smart discuss context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
```
Display confirmation:

View File

@@ -6,7 +6,7 @@ Calculate the next decimal phase number for urgent insertions.
```bash
# Get next decimal phase after phase 6
gsd-sdk query phase.next-decimal 6
gsd-tools query phase.next-decimal 6
```
Output:
@@ -32,13 +32,13 @@ With existing decimals:
## Extract Values
```bash
DECIMAL_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --pick next)
BASE_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --pick base_phase)
DECIMAL_PHASE=$(gsd-tools query phase.next-decimal "${AFTER_PHASE}" --pick next)
BASE_PHASE=$(gsd-tools query phase.next-decimal "${AFTER_PHASE}" --pick base_phase)
```
Or with --raw flag:
```bash
DECIMAL_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --raw)
DECIMAL_PHASE=$(gsd-tools query phase.next-decimal "${AFTER_PHASE}" --raw)
# Returns just: 06.1
```
@@ -56,7 +56,7 @@ DECIMAL_PHASE=$(gsd-sdk query phase.next-decimal "${AFTER_PHASE}" --raw)
Decimal phase directories use the full decimal number:
```bash
SLUG=$(gsd-sdk query generate-slug "$DESCRIPTION" --raw)
SLUG=$(gsd-tools query generate-slug "$DESCRIPTION" --raw)
PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
mkdir -p "$PHASE_DIR"
```

View File

@@ -51,7 +51,7 @@ Phases:
What to commit:
```bash
gsd-sdk query commit "docs: initialize [project-name] ([N] phases)" --files .planning/
gsd-tools query commit "docs: initialize [project-name] ([N] phases)" --files .planning/
```
</format>
@@ -136,7 +136,7 @@ SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
What to commit:
```bash
gsd-sdk query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
gsd-tools query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
```
**Note:** Code files NOT included - already committed per-task.
@@ -156,7 +156,7 @@ Current: [task name]
What to commit:
```bash
gsd-sdk query commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
gsd-tools query commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
```
</format>
@@ -287,7 +287,7 @@ Set `commit_docs: false` so planning docs stay local and are not committed to an
Instead of the standard `commit` command, use `commit-to-subrepo` when `sub_repos` is configured:
```bash
gsd-sdk query commit-to-subrepo "feat(02-01): add user API" \
gsd-tools query commit-to-subrepo "feat(02-01): add user API" \
--files backend/src/api/users.ts backend/src/types/user.ts frontend/src/components/UserForm.tsx
```

View File

@@ -1,6 +1,6 @@
# Git Planning Commit
Commit planning artifacts via `gsd-sdk query commit`, which checks `commit_docs` config and gitignore status (same behavior as legacy `gsd-tools.cjs commit`).
Commit planning artifacts via `gsd-tools query commit`, which checks `commit_docs` config and gitignore status (same behavior as legacy `gsd-tools.cjs commit`).
## Commit via CLI
@@ -9,7 +9,7 @@ Pass the message first, then file paths via `--files`. Both `commit` and `commit
Always use this for `.planning/` files — it handles `commit_docs` and gitignore checks automatically:
```bash
gsd-sdk query commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
gsd-tools query commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
```
The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.planning/` is gitignored. No manual conditional checks needed.
@@ -19,7 +19,7 @@ The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.pla
To fold `.planning/` file changes into the previous commit:
```bash
gsd-sdk query commit "" --files .planning/codebase/*.md --amend
gsd-tools query commit "" --files .planning/codebase/*.md --amend
```
## Commit Message Patterns

View File

@@ -14,7 +14,7 @@ From `$ARGUMENTS`:
The `find-phase` command handles normalization and validation in one step:
```bash
PHASE_INFO=$(gsd-sdk query find-phase "${PHASE}")
PHASE_INFO=$(gsd-tools query find-phase "${PHASE}")
```
Returns JSON with:
@@ -45,7 +45,7 @@ fi
Use `roadmap get-phase` to validate phase exists:
```bash
PHASE_CHECK=$(gsd-sdk query roadmap.get-phase "${PHASE}" --pick found)
PHASE_CHECK=$(gsd-tools query roadmap.get-phase "${PHASE}" --pick found)
if [ "$PHASE_CHECK" = "false" ]; then
echo "ERROR: Phase ${PHASE} not found in roadmap"
exit 1
@@ -57,5 +57,5 @@ fi
Use `find-phase` for directory lookup:
```bash
PHASE_DIR=$(gsd-sdk query find-phase "${PHASE}" --raw)
PHASE_DIR=$(gsd-tools query find-phase "${PHASE}" --raw)
```

View File

@@ -55,7 +55,7 @@ Group by plan, dimension, severity.
### Step 6: Commit
```bash
gsd-sdk query commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
gsd-tools query commit "fix($PHASE): revise plans based on checker feedback" --files .planning/phases/$PHASE-*/$PHASE-*-PLAN.md
```
### Step 7: Return Revision Summary

View File

@@ -55,19 +55,19 @@ Configuration options for `.planning/` directory behavior.
- User must add `.planning/` to `.gitignore`
- Useful for: OSS contributions, client projects, keeping planning private
**Using `gsd-sdk query` (preferred):**
**Using `gsd-tools query` (preferred):**
```bash
# Commit with automatic commit_docs + gitignore checks:
gsd-sdk query commit "docs: update state" --files .planning/STATE.md
gsd-tools query commit "docs: update state" --files .planning/STATE.md
# Load config via state load (returns JSON):
INIT=$(gsd-sdk query state.load)
INIT=$(gsd-tools query state.load)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
# commit_docs is available in the JSON output
# Or use init commands which include commit_docs:
INIT=$(gsd-sdk query init.execute-phase "1")
INIT=$(gsd-tools query init.execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
# commit_docs is included in all init command outputs
```
@@ -77,7 +77,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
**Commit via CLI (handles checks automatically):**
```bash
gsd-sdk query commit "docs: update state" --files .planning/STATE.md
gsd-tools query commit "docs: update state" --files .planning/STATE.md
```
The CLI checks `commit_docs` config and gitignore status internally — no manual conditionals needed.
@@ -165,14 +165,14 @@ To use uncommitted mode:
Use `init execute-phase` which returns all config as JSON:
```bash
INIT=$(gsd-sdk query init.execute-phase "1")
INIT=$(gsd-tools query init.execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
# JSON output includes: branching_strategy, phase_branch_template, milestone_branch_template
```
Or use `state load` for the config values:
```bash
INIT=$(gsd-sdk query state.load)
INIT=$(gsd-tools query state.load)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
# Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
```

View File

@@ -34,7 +34,7 @@ Reference: `references/questioning.md` for the full anti-pattern list.
## State Management Anti-Patterns
15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd-sdk query` for registered state/roadmap handlers (e.g. `state.update`, `state.advance-plan`, `roadmap.update-plan-progress`), or legacy `node …/gsd-tools.cjs` for CLI-only commands. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
15. **No direct Write/Edit to STATE.md or ROADMAP.md for mutations.** Always use `gsd-tools query` for registered state/roadmap handlers (e.g. `state.update`, `state.advance-plan`, `roadmap.update-plan-progress`), or legacy `node …/gsd-tools.cjs` for CLI-only commands. Direct Write tool usage bypasses safe update logic and is unsafe in multi-session environments. Exception: first-time creation of STATE.md from template is allowed.
## Behavioral Rules
@@ -53,7 +53,7 @@ Reference: `references/questioning.md` for the full anti-pattern list.
## GSD-Specific Rules
24. **Do not** check for `mode === 'auto'` or `mode === 'autonomous'` -- GSD uses `yolo` config flag. Check `yolo: true` for autonomous mode, absence or `false` for interactive mode.
25. **Prefer `gsd-sdk query`** for orchestration when a handler exists; when shelling out to the legacy CLI, use **`gsd-tools.cjs`** (not `gsd-tools.js` or any other filename) — GSD ships the programmatic API as CommonJS for Node.js CLI compatibility.
25. **Prefer `gsd-tools query`** for orchestration when a handler exists; when shelling out to the legacy CLI, use **`gsd-tools.cjs`** (not `gsd-tools.js` or any other filename) — GSD ships the programmatic API as CommonJS for Node.js CLI compatibility.
26. **Plan files MUST follow `{padded_phase}-{NN}-PLAN.md` pattern** (e.g., `01-01-PLAN.md`). Never use `PLAN-01.md`, `plan-01.md`, or any other variation -- gsd-tools detection depends on this exact pattern.
27. **Do not start executing the next plan before writing the SUMMARY.md for the current plan** -- downstream plans may reference it via `@` includes.

View File

@@ -14,7 +14,7 @@ The user-flow form mirrors what a real user does: open, fill, click, see. No HTT
## When this framing applies
The framing fires when:
- The phase under verification has `**Mode:** mvp` in ROADMAP.md (parsed via `gsd-sdk query roadmap.get-phase --pick mode`).
- The phase under verification has `**Mode:** mvp` in ROADMAP.md (parsed via `gsd-tools query roadmap.get-phase --pick mode`).
- AND the phase has a user-story-formatted goal (set by `/gsd mvp-phase` per Phase 2): "As a [user role], I want to [capability], so that [outcome]."
If the phase has `mode: mvp` but the goal is NOT in user-story format, the verifier surfaces this as a discrepancy and asks the user to run `/gsd mvp-phase` to reformat the goal — same pattern as the planner agent under MVP_MODE (per `references/planner-mvp-mode.md`).

View File

@@ -93,19 +93,19 @@ This ensures workstream scope chains automatically through the workflow:
## CLI Usage
```bash
# All gsd-sdk query commands accept --ws
gsd-sdk query state.json --ws feature-a
gsd-sdk query find-phase 3 --ws feature-b
# All gsd-tools query commands accept --ws
gsd-tools query state.json --ws feature-a
gsd-tools query find-phase 3 --ws feature-b
# Session-local switching without --ws on every command
GSD_SESSION_KEY=my-terminal-a gsd-sdk query workstream.set feature-a
GSD_SESSION_KEY=my-terminal-a gsd-sdk query state.json
GSD_SESSION_KEY=my-terminal-b gsd-sdk query workstream.set feature-b
GSD_SESSION_KEY=my-terminal-b gsd-sdk query state.json
GSD_SESSION_KEY=my-terminal-a gsd-tools query workstream.set feature-a
GSD_SESSION_KEY=my-terminal-a gsd-tools query state.json
GSD_SESSION_KEY=my-terminal-b gsd-tools query workstream.set feature-b
GSD_SESSION_KEY=my-terminal-b gsd-tools query state.json
# Workstream CRUD
gsd-sdk query workstream.create <name>
gsd-sdk query workstream.list
gsd-sdk query workstream.status <name>
gsd-sdk query workstream.complete <name>
gsd-tools query workstream.create <name>
gsd-tools query workstream.list
gsd-tools query workstream.status <name>
gsd-tools query workstream.complete <name>
```