get-shit-done 3605 修复：清除 Agent 契约中的废弃斜杠命令引用及其回归守卫

本篇围绕 get-shit-done（GSD）仓库中的变更记录 .changeset/3605-stale-agent-command-refs.md 展开，完整还原 Issue #3605 的修复内容：五个 agent 契约文件中残留的 6 处废弃斜杠命令引用（/gsd-research-phase、/gsd-insert-phase）如何被替换为现行命令（/gsd:plan-phase --research-phase <N>、/gsd:phase insert），以及新增的回归守卫测试 tests/bug-3605-stale-research-insert-phase-agent-refs.test.cjs 如何保证这类"命令退役后引用残留"问题不再复发。读完后你将掌握 GSD 斜杠命令命名空间演进的来龙去脉、命令整合（consolidation）清理中的目录盲区成因，以及如何为"文本即部署产物"的 Markdown 契约编写可运行的回归守卫。

变更记录原文：一条 Fixed 类型的 Changeset 碎片

GSD 采用 per-PR 的 changeset 碎片管理 CHANGELOG：每个有用户可见变更的 PR 向 .changeset/ 目录投下一个带 frontmatter 的 .md 片段，发布时由 scripts/changeset/ 下的工具汇总进 CHANGELOG.md 并删除已消费的碎片（机制见 .changeset/README.md）。#3605 的碎片内容如下（原文完整保留）：

---
type: Fixed
issue: 3605
---
**Agent contracts no longer reference retired `/gsd-research-phase` or
`/gsd-insert-phase`** — six surviving references in `agents/gsd-executor.md`,
`agents/gsd-phase-researcher.md`, `agents/gsd-planner.md`,
`agents/gsd-research-synthesizer.md`, and `agents/gsd-roadmapper.md` are replaced
with `/gsd:plan-phase --research-phase <N>` and `/gsd:phase insert`. Adds a
regression guard (`tests/bug-3605-stale-research-insert-phase-agent-refs.test.cjs`)
that fails when any retired command name reappears in `agents/*.md` — covers the
gap that let #3029, #3044, and #3131 miss the `agents/` directory.

拆解这条记录，它包含三个关键事实：

1. 修复对象：agents/ 目录下的 5 个 agent 契约文件（executor、phase-researcher、planner、research-synthesizer、roadmapper），合计 6 处废弃命令引用；
2. 替换目标：/gsd-research-phase → /gsd:plan-phase --research-phase <N>，/gsd-insert-phase → /gsd:phase insert；
3. 防回归手段：新增一个测试守卫，任何退役命令名再次出现在 agents/*.md 中都会让测试失败，并且该守卫恰好堵上了此前三次清理（#3029、#3044、#3131）都漏掉 agents/ 目录的盲区。

背景：为什么这些命令被"退役"

GSD 的斜杠命令经历了一轮命名空间与功能整合：命令从旧式 /gsd-<name> 连字符形式迁移到 /gsd:<name> 冒号命名空间形式，同时部分独立命令被合并进更通用的命令。与 #3605 直接相关的两次整合是：

• /gsd-research-phase 被删除：由 /gsd-plan-phase --research-phase <N> 取代。现行命令定义在 commands/gsd/plan-phase.md，其中明确写道：Research-only 模式（--research-phase <N>）会为指定阶段 N 派生 gsd-phase-researcher、写出 RESEARCH.md 然后在 planner 运行前退出，适用于跨阶段研究、规划前的文档评审、以及"只迭代研究而不重新派生 planner"的纠正循环；该模式即替代了被删除的 research-phase 命令（上游 Issue #3042）。
• /gsd-insert-phase 被并入 /gsd-phase：v1.40.0 将独立命令整合为子命令形式。现行 commands/gsd/phase.md 中的 --insert 标志负责把紧急工作以小数阶段（如 72.1）插入到已有阶段之间，底层复用 insert-phase workflow。

这两次整合都做了"全局搜索替换"式的清理，但各自的清理范围（scrub scope）没有把 agents/ 目录纳入"退役名替换"的覆盖列表，于是 6 处引用在多次 PR 之后依然存活。

修复落地：被替换的 6 处引用长什么样

修复后的 agents/ 目录中，相关引用已全部指向现行命令，仓库现状可逐一验证：

• agents/gsd-phase-researcher.md 第 17 行：Spawned by /gsd:plan-phase(integrated) or/gsd:plan-phase --research-phase (standalone). —— 说明该 agent 由整合模式或独立的 --research-phase 模式派生；
• agents/gsd-planner.md 第 186 行：针对利基领域（3D/游戏/音频/shader/ML）先建议 /gsd:plan-phase --research-phase <N>；
• agents/gsd-executor.md 第 195 行：依赖包不存在时的兜底步骤是"重新运行 /gsd:plan-phase --research-phase <N> 以查明正确包名"；
• agents/gsd-research-synthesizer.md 第 115 行：研究综合时评估哪些阶段在规划期可能需要 /gsd:plan-phase --research-phase <N>。

这些文本不是普通文档注释——如守卫测试头部注释所强调的：agents/*.md 文本本身就是部署出去的契约（"the deployed contract"）。Claude Code、Codex 等运行时会在运行时加载这些文件并把内容呈现给真实用户，因此其中写错的命令名会直接误导用户去敲一个不存在的命令。这正是 #3605 必须作为 Fixed 类型（而非纯内部重构）进 CHANGELOG 的原因。

盲区成因：命名空间转换器为什么救不了"退役名"

要理解为什么三次清理都能漏掉 agents/，需要看仓库里唯一的批量命令改写工具 scripts/fix-slash-commands.cjs。该脚本是"双向 GSD 斜杠命令命名空间归一器"，其 SEARCH_DIRS 列表明确包含 agents/ 目录（第 22–31 行）：

const SEARCH_DIRS = [
  path.join(__dirname, '..', 'get-shit-done', 'bin', 'lib'),
  path.join(__dirname, '..', 'get-shit-done', 'workflows'),
  path.join(__dirname, '..', 'get-shit-done', 'references'),
  path.join(__dirname, '..', 'get-shit-done', 'templates'),
  path.join(__dirname, '..', 'get-shit-done', 'contexts'),
  path.join(__dirname, '..', 'commands', 'gsd'),
  path.join(__dirname, '..', 'agents'),
  path.join(__dirname, '..', 'hooks'),
];

但它的转换逻辑是按"存活命令名注册表"驱动的：readCmdNames() 从 commands/gsd/*.md 读取当前存在的命令名，transformContent() 只做 /gsd-<cmd> → /gsd:<cmd> 的命名空间改写（第 46–66 行），且刻意不触碰非命令标识符（如 gsd-sdk、gsd-tools）。这意味着：

• 对仍然存活的命令，连字符旧写会被自动纠正为冒号形式；
• 对已退役的命令（commands/gsd/ 下已无对应 .md 文件），/gsd-research-phase、/gsd-insert-phase 这类名字根本不在注册表里，任何方向都不会被改写——它们既不是合法的旧写法，也没有对应的替换目标，脚本只能让它们原样存活。

从源码结构看，这不是 bug 而是职责边界：该脚本的定位是命名空间形式的归一化，而非"命令生命周期管理"。命令被删除后旧引用的清除，必须依靠每次整合 PR 各自的全局搜索替换——而 #3029、#3044、#3131 三次整合的 per-name scrub 范围都没有包含 agents/，才留下了 #3605 这 6 处残留。

回归守卫：tests/bug-3605-stale-research-insert-phase-agent-refs.test.cjs 的实现剖析

本次修复最有价值的部分是把"一次性清理"固化成了可运行的不变量。守卫测试 tests/bug-3605-stale-research-insert-phase-agent-refs.test.cjs 的完整机制如下：

1. 退役命令黑名单

const RETIRED_COMMANDS = [
  '/gsd-research-phase',
  '/gsd-insert-phase',
  '/gsd-add-phase',
  '/gsd-remove-phase',
  '/gsd-analyze-dependencies',
];

黑名单不止包含 #3605 直接涉及的两个命令，而是把 agents/ 契约中任何已知退役的命令名都纳入，使守卫具备前向防御能力。

2. 逐文件、逐行的带词边界扫描

scanForRetired()（第 43–66 行）对每个 agents/*.md 文件逐行查找黑名单命中，并刻意做了词边界判定：只有当命中位置之后紧跟的字符不属于 [A-Za-z0-9-_] 时才计为一次"真实调用"，避免把更长命令名的前缀（例如假想的 /gsd-research-phase-x）误报为退役命令引用。实现上用 charCodeAt 显式枚举数字、大小写字母、- 与 _ 四类"名字字符"：

const next = lines[i].charCodeAt(idx + cmd.length);
// Only count if the match is a real invocation, not a prefix of a longer name.
// The next char must be a non-name char (anything outside [A-Za-z0-9-_]).
const isWordBoundary =
  Number.isNaN(next) ||
  !((next >= 48 && next <= 57) || // 0-9
    (next >= 65 && next <= 90) || // A-Z
    (next >= 97 && next <= 122) || // a-z
    next === 45 || // -
    next === 95); // _

3. 对全部 agent 文件生成断言

describe 块（第 68–86 行）先列出 agents/ 下所有 .md 文件，附带一个 smoke 断言（目录非空，防止守卫在错误路径上"空跑通过"），然后为每个文件生成一条独立断言：命中列表必须为空数组，失败信息会打印出具体行号、命中的命令名和该行原文，定位成本极低：

test(`${rel} contains no retired slash commands`, () => {
  const hits = scanForRetired(file);
  assert.deepEqual(
    hits,
    [],
    `${rel} contains retired command references:\n` +
      hits.map((h) => `  line ${h.line}: ${h.cmd} — ${h.text}`).join('\n'),
  );
});

文件头部还保留了审计豁免注释（allow-test-rule: source-text-is-the-product），说明这条"在源码文本上 grep"的测试之所以成立，是因为被 grep 的文本就是用户最终看到的产品表面。测试使用 node:test + node:assert 标准库实现，无外部依赖，直接扫描仓库根下的 agents/ 目录。

如何验证与复现

在仓库根目录下运行该守卫测试即可验证当前状态：

node --test tests/bug-3605-stale-research-insert-phase-agent-refs.test.cjs

预期结果：smoke 测试通过 + 每个 agents/*.md 文件一条"contains no retired slash commands"断言全部通过。若有人向 agent 契约中重新引入 /gsd-research-phase 等退役名，对应文件的断言会失败并输出行级定位。

如果你想理解这类问题是如何"漏"进来的，可以配合阅读三处源码：整合清理时依赖的 scripts/fix-slash-commands.cjs（只做存活命令的命名空间改写）、现行命令定义 commands/gsd/plan-phase.md（--research-phase 模式即 /gsd-research-phase 的替代者）与 commands/gsd/phase.md（--insert 子命令即 /gsd-insert-phase 的归宿）。

对"Markdown 即契约"类项目的工程启示

#3605 虽然只是 6 处文本替换，但它揭示了一类通用问题：当项目的行为定义存在于 Markdown 文本（agent 契约、命令文档、workflow 脚本）而非编译型代码中时，命令重命名/合并这类"破坏性变更"的回归测试不能只覆盖代码，必须把文本表面也纳入不变量检查。get-shit-done 的解法有三个可迁移的要点：

1. 给退役命令维护显式黑名单，而不是靠"新名字必须出现"的正向断言——黑名单能同时拦截旧引用复活和新文件带入旧引用两种回归；
2. 匹配必须带词边界，否则前缀误报会让守卫失去可信度；
3. 为守卫加 smoke 断言（确认至少扫到了文件），防止目录重命名等结构性变更让守卫静默空转。

从本次修复的边界看：它只保证 agents/*.md 这一表面干净（这也是三次历史清理共同遗漏的表面）；仓库中其他表面（如 get-shit-done/workflows/、commands/）的命令一致性由其他守卫（如 lint-no-source-grep 系列脚本与 bug-2950-stale-command-refs.test.cjs）各自负责。理解这条分工，就能准确把握 #3605 守卫在整体测试版图中的位置。