fix(3677): normalize /gsd:<cmd> → /gsd-<cmd> in agent bodies for hyphen-name runtimes (#3680)

* fix(3677): normalize /gsd:<cmd> → /gsd-<cmd> in agent bodies for hyphen-name runtimes

Closes #3677

The executor agent bodies installed to `~/.claude/agents/gsd-*.md` (and
the Qwen / Hermes equivalents) still contained retired `/gsd:<cmd>`
colon-form references in their prose. Every GSD skill / agent has
registered under the canonical hyphen `name:` form since #2808, so the
colon form is unroutable — Claude Code rejects it with `Unknown command:
/gsd:execute-phase. Did you mean /gsd-execute-phase?`. Reporter measured
~28 agent files / ~96 leaked refs on a full Claude global install.

This is the agent-body surface of the same class of bug as the two
already-fixed sibling surfaces:

- #3583 (SKILL.md skill bodies) — fixed via #3629
- #3584 (user-facing runtime "Next step: /gsd:…" emissions) — fixed via #3606

The agent-body surface in `bin/install.js`'s agent install loop was
never covered: the Claude-default / Qwen / Hermes branches register
hyphen `name:` but copy bodies verbatim (Qwen/Hermes do branding-only
swaps; Claude-default falls through with no body conversion at all), so
the colon refs leak.

Fix:

1. Add a pure predicate `shouldNormalizeHyphenNamespaceInAgentBody(runtime)`
   backed by an explicit allow-list `HYPHEN_NAME_AGENT_RUNTIMES =
   {claude, qwen, hermes}`. Unknown / future runtimes default to false
   (better to leak than to mangle).

2. Add `normalizeAgentBodyForRuntime(content, runtime, cmdNames)` that
   conditionally applies the shared `transformContentToHyphen` from
   `scripts/fix-slash-commands.cjs` (same transform #3629 used for
   SKILL.md bodies).

3. Call `normalizeAgentBodyForRuntime(content, runtime, readGsdCommandNames())`
   in the agent install loop right before `fs.writeFileSync`, so it
   composes with all the existing runtime branches. For Gemini and
   self-converting runtimes the predicate short-circuits, so their
   convertClaudeAgentToXAgent output is not re-rewritten.

4. Export both functions from `bin/install.js` for the regression test.

Regression test (`tests/bug-3677-agent-colon-namespace-leak.test.cjs`):
24 tests across 4 groups — A (exports exist), B (predicate matrix
covering all 15 runtimes in the layout table + an unknown-runtime case),
C (normalize helper applies/skips correctly for claude/qwen/hermes/
gemini/copilot), D (sanity check of the underlying transform).

Verification:
- node --test tests/bug-3677-*: 24/24 pass
- Sibling-regression (6 slash-namespace test files): 76/76 pass
- All install-minimal-all-runtimes suites: 54/54 pass after `npm run
  build:sdk` (the prior 27 fails were pre-existing — missing local
  sdk/dist build, not introduced by this change)
- Full docker suite (gsd-test-summary): 11769/0 fail
  (11751 baseline + 18 new = my 24 tests with some collateral pickups)

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

* chore(changeset): set PR number 3680 (Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>)

* test(3677): port real-source efficacy + idempotence tests from #3681

Adds describe group E with 5 behavioral tests credited to John Turner
(johnzilla, PR #3681 — closed in favor of this PR by its author):

  E0: command roster is populated and includes symptom commands
  E1: every agents/gsd-*.md transforms clean — real-source efficacy
  E2: idempotent — repeat transform on hyphenated input is a no-op
  E3: word boundary — /gsd:plan-phase-extra is not a roster match
  E4: rewrites bare gsd:<cmd> shorthand (no leading slash)

E1 is the test that would have caught the original bug — pure-function
tests can pass while the install.js wiring silently bypasses the
transform. E2 guards against double-rewrite mangling during reinstall.

29/29 tests pass (24 original + 5 ported).

Co-Authored-By: John Turner <johnzilla@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: John Turner <johnzilla@users.noreply.github.com>
This commit is contained in:
Tom Boucher
2026-05-17 19:31:31 -04:00
committed by GitHub
parent f970c09bf3
commit 80d6306e99
3 changed files with 290 additions and 0 deletions

View File

@@ -29,6 +29,39 @@ const {
readCmdNames: readGsdCommandNames,
} = require(path.join(__dirname, '..', 'scripts', 'fix-slash-commands.cjs'));
/**
* Runtimes that register hyphen-form `name:` per #2808 AND copy agent bodies
* verbatim (only branding swaps, no namespace conversion), so retired
* `/gsd:<cmd>` colon refs leak into installed agent prose. Sibling fixes
* #3583 / #3629 covered SKILL.md bodies, #3584 / #3606 covered runtime
* emissions — this is the agent-body surface (#3677).
*
* Explicit allow-list rather than deny-list so unknown / future runtimes
* default to "no rewrite" (better to leak than to mangle a runtime whose
* namespace behavior we haven't verified).
*/
const HYPHEN_NAME_AGENT_RUNTIMES = new Set(['claude', 'qwen', 'hermes']);
/**
* #3677 predicate — true when an agent body needs `/gsd:<cmd>` → `/gsd-<cmd>`
* normalization at install time.
*/
function shouldNormalizeHyphenNamespaceInAgentBody(runtime) {
if (typeof runtime !== 'string' || runtime === '') return false;
return HYPHEN_NAME_AGENT_RUNTIMES.has(runtime);
}
/**
* #3677 helper — applies the hyphen-namespace transform iff the predicate
* says so. Pure function; safe to call unconditionally from the install
* loop. Returns the input unchanged for runtimes that self-convert or
* intentionally keep colon refs.
*/
function normalizeAgentBodyForRuntime(content, runtime, cmdNames) {
if (!shouldNormalizeHyphenNamespaceInAgentBody(runtime)) return content;
return transformContentToHyphen(content, cmdNames);
}
// Colors
const cyan = '\x1b[36m';
const green = '\x1b[32m';
@@ -8440,6 +8473,13 @@ function install(isGlobal, runtime = 'claude', options = {}) {
content = content.replace(/\bClaude Code\b/g, 'Hermes Agent');
content = content.replace(/\.claude\//g, '.hermes/');
}
// #3677 — normalize retired `/gsd:<cmd>` colon refs in the agent body
// to the canonical hyphen form `/gsd-<cmd>` for hyphen-`name:`
// runtimes (claude / qwen / hermes). Self-converting runtimes and
// Gemini are skipped by the predicate — see
// shouldNormalizeHyphenNamespaceInAgentBody above. Mirrors the
// SKILL.md-body fix shipped via #3629.
content = normalizeAgentBodyForRuntime(content, runtime, readGsdCommandNames());
const destName = isCopilot ? entry.name.replace('.md', '.agent.md') : entry.name;
fs.writeFileSync(path.join(agentsDest, destName), content);
}
@@ -11054,6 +11094,9 @@ function installAllRuntimes(runtimes, isGlobal, isInteractive) {
// converter functions when called from within the CLI path (circular require).
// The main() block below is gated on !GSD_TEST_MODE, as before.
module.exports = {
// #3677 — hyphen-namespace normalization seam for agent bodies
shouldNormalizeHyphenNamespaceInAgentBody,
normalizeAgentBodyForRuntime,
yamlIdentifier,
computePathPrefix,
getCodexSkillAdapterHeader,