GSD 命令表面清理实战：如何彻底消除「Unknown command」陈日斜杠路由残留

本文以 gsd-core 仓库中的 changeset 归档记录（scrub-stale-command-routes.md，PR #3029）为骨架，深入讲解「命令合并（command consolidation）之后，用户可见面上的陈旧斜杠命令引用如何被系统性清理」这一工程问题。你将理解/gsd-code-review-fix与/gsd-plan-milestone-gaps被合并的来龙去脉、Unknown command错误的产生机制与类型化诊断方式，以及 GSD 如何用注册表断言 + 工作流文件断言两层测试护栏，保证合并后的命令表面零残留。

问题背景：命令合并后，斜杠命令为什么还会「过期」

GSD（Git. Ship. Done）把大量操作封装为/gsd-<name>形式的斜杠命令，每条命令对应 commands/gsd/ 目录下一个带 frontmatter 的命令文件。为了削减技能清单的维护开销，GSD 在 v1.40.0 前后发起了「技能表面合并（Skill Surface Consolidation）」工程，把 31 个微技能折叠进 4 个新的分组父命令与 6 个既有父命令，子操作统一降级为父命令的 flag（详见 skill-surface-consolidation.md）。

本次清理涉及的两个命令正是这场合并的产物：

以代码评审为例，合并后的命令签名在 code-review.md 的argument-hint中完整保留：

<phase-number> [--depth=quick|standard|deep] [--files file1,file2,...] [--fix [--all] [--auto]] [reviewer-lane flags]

其中--fix说明写道：评审完成后自动应用发现的问题并派发 gsd-code-fixer agent；--all把 Info 级别发现也纳入修复范围（默认仅 Critical + Warning）；--auto开启「修复 + 复审」迭代循环，最多 3 轮。

问题由此产生：命令本体被合并了，但若干用户可见面（user-facing surface）的「推荐文本 / offer 文本」仍在输出旧命令名。用户点击或输入这些推荐后，分发器找不到对应命令，只能回退到Unknown command错误——功能并非不存在，而是「入口文本」过期了。这正是 changeset 标题中 scrub（擦除）一词的由来：不是新功能，而是对陈旧命令路由的系统性清扫。

症状识别：「Unknown command」是怎么产生的

要理解这次修复的价值，先要知道Unknown command从何而来。GSD 的命令分发链路在 gsd-core/bin/gsd-tools.cjs 中逐级尝试：capability 分发 → overlay 分发 → host 分发表（ADR-2346）→ 兜底的未知命令错误。当所有分发路径都未命中时，gsd-tools.cjs 会以SDK_UNKNOWN_COMMAND错误原因输出Unknown command: <command>：

error(`Unknown command: ${command}${suggestion}`, ERROR_REASON.SDK_UNKNOWN_COMMAND);

有意思的是，源码还处理了一个边界情况（#3243）：如果调用者传入foo.bar这样的点分形式，shim 会拆出头部foo，此时错误信息会附带建议——Unknown command: foo — did you mean: "foo bar"?，避免只抛一句干巴巴的 unknown。

从路由器的角度看，Unknown command是一个类型化错误而非普通文本。在 cjs-command-router-adapter.cts 中，Hub 分发结果被判定为ERROR_KINDS.UnknownCommand后，会以双参数形式调用error(msg, ERROR_REASON.SDK_UNKNOWN_COMMAND)，从而在GSD_JSON_ERRORS=1的 JSON 错误信封里保留reason: 'sdk_unknown_command'供下游消费；task-command-router.cts 对未知子命令也采用同样的原因码。SDK_UNKNOWN_COMMAND枚举值定义于 src/io.cts。

因此，用户在某处看到/gsd-code-review-fix并触发它时，本质上是注册表（registry）与实际命中的命令表面不一致：命令文件已删除，但引用它的文本还活着。

修复范围：六个必须同步的用户可见面

本次修复（PR #3029，关闭 #3029/#3034）逐一清点了仍然输出旧命令名的面，共六类。下面结合当前仓库状态逐一印证：

1. audit-milestone 的 offer 块

/gsd-audit-milestone是里程碑审计的总指挥命令（orchestrator），其流程见 audit-milestone.md：读取各阶段的*-SUMMARY.md与*-VERIFICATION.md，聚合技术债与延迟 gap，再派发 integration checker 做跨阶段接线检查。它正是/gsd-plan-milestone-gaps合并后的新家——gap 规划内联发生在审计输出中，因此 offer 文本绝不能把用户再引向已删除的独立命令。

2. gsd-complete-milestone 的路由逻辑

complete-milestone.md 的requires声明直接依赖audit-milestone，其路由分支明确规定：

• 找不到里程碑审计时：提示先跑/gsd:audit-milestone验证；
• 审计状态为gaps_found时：不再建议一个独立的 gap 规划命令，而是直接说明「审计输出已枚举 gap」，并要求用户用/gsd:phase --insert <N>插入补缺阶段、补齐验证链；若选择跳过，则把 gap 作为技术债接受。

这种「审计 → 枚举 gap → 插入补缺阶段」的内联链路，就是原/gsd-plan-milestone-gaps的替代形态。

3. code-review / execute-phase 的 offer 文本

执行阶段与代码评审相关的推荐文本统一改为新形态。命名空间命令 ns-review.md 第 12 行明确记录了这一迁移事实：gsd-code-review-fixwas absorbed bygsd-code-review --fixin #2790，其路由表只指向gsd-code-review等存活命令。

4. gsd-code-fixer agent 的角色卡片

gsd-code-fixer.md 是负责读取 REVIEW.md、对评审发现逐条打补丁并原子提交的 agent。它的 frontmatter 描述与正文均已切换到新身份：由/gsd:code-review --fix工作流派发、产出 REVIEW-FIX.md 工件，并自带崩溃自愈逻辑（检测到.review-fix-recovery-pending.json哨兵时清理孤儿 worktree 后重跑）。角色卡片中不再出现旧命令名。

5. 文档面：USER-GUIDE、FEATURES、INVENTORY、AGENTS、CONFIGURATION

GSD 把文档当作「命令表面的镜像」对待，因此五份核心文档必须与注册表同步：

• FEATURES.md 的 REQ-CONSOLIDATE-04 明确规定：被删除的微技能斜杠形式（包括gsd-code-review-fix在内的一长串名单）必须解析为 "Unknown command"，不允许存在影子桩（no shadow stubs）；REQ-CONSOLIDATE-05 则要求autonomous.md一律调用/gsd-code-review --fix；
• CONFIGURATION.md 的workflow.code_review配置项（默认true）描述为「Enable/gsd-code-reviewand/gsd-code-review --fixcommands」，只在开关关闭时以配置门禁消息退出——入口文本是合并后的形态；
• AGENTS.md 在高级与专用 agent 章节写明 gsd-code-fixer 由/gsd-code-review --fix派发；
• USER-GUIDE 与 INVENTORY 属于同一批「注册表面」文档，同样纳入本次清理。

6. 命名空间命令与技能文件的内部注释

虽然严格说不属于「offer 文本」，但为了让未来的维护者不再误用，命名空间命令文件里保留了明确的迁移注释。例如 ns-project.md 第 12-13 行：

gsd-plan-milestone-gapswas deleted by #2790 — gap planning now happens inline as part ofgsd-audit-milestone's output.

与之对应的技能文件 SKILL.md 与 SKILL.md 保持了同样的说明。这类「删除原因就地说明」是防止旧命令名复活的低成本护栏。

测试护栏：注册表断言与文件级断言

清理是否彻底，不能靠人工校对。仓库用两层自动化断言把「陈旧命令零残留」固化为可回归的契约。

第一层：实时注册表（live registry）断言

tests/docs-parity-live-registry.test.cjs 维护一个「活命令令牌集合」getLiveCommandTokens()：解析commands/gsd/下每个命令文件的 frontmattername:字段（兼容gsd:foo与gsd-foo两种写法），为每个存活命令生成/gsd-foo、/gsd:foo、$gsd-foo三种令牌。基于它：

• 断言删除的命令不得出现在注册表：registry must NOT contain removed /gsd-code-review-fix、/gsd-plan-milestone-gaps must not be in the live registry（同批还有/gsd-reapply-patches、/gsd-status）；
• 反向断言合并后的父命令与 flag 形态必须出现：/gsd-code-review --fix等新形式在 help 全量文档中可查（help/modes/full.md 是 #3039 之后的正典命令参考）；
• 双向一致性：do.md路由表（/gsd-progress --do运行时实际派发的分发器）中引用的每个/gsd[-:]<name>令牌都必须解析到存活命令，否则分发器就会发出Unknown command。

第二层：工作流文件级断言

同文件内还折叠了源自 bug #2950 的「陈旧命令引用」回归测试（folded:bug-2950-stale-command-refs）。它维护了一份DELETED_COMMANDS名单（含/gsd-code-review-fix），并对help/modes/full.md、do.md、settings.md、discuss-phase.md、new-project.md、plan-phase.md、spike.md、sketch.md等受影响工作流文件逐文件断言：

1. 每个受影响文件不包含任何已删除命令名；
2. 每个(文件, 旧命令, 新形式)三元组断言新形式存在，例如settings.md中/gsd-code-review-fix必须替换为/gsd:code-review --fix；
3. 兜底的 blanket check：遍历受影响文件 × 删除名单的全部组合，任何一个文件残留旧命令名即测试失败。

配套断言：技能清单与命令文档

• skill-manifest.test.cjs 在命名空间技能的路由目标白名单中注明'gsd-code-review'的--fix吸收了原gsd-code-review-fix，确保路由目标全部解析到存活命令文件或已知合并父命令；
• code-review.test.cjs 专门为 #2790 添加断言：code-review.md必须文档化--fixflag（吸收自code-review-fix）、argument-hint必须包含--fix，并对code-review-fix.md工作流的 initialize 步骤、gsd-code-fixer 引用与迭代上限做结构校验。

维护启示：删除命令的正确姿势

结合 FEATURES.md 的 REQ-CONSOLIDATE 系列与本次 scrub，可以从仓库实践中提炼出「删除一条 GSD 斜杠命令」的完整检查清单：

1. 合并功能而非删除功能：把子操作降级为父命令 flag（如--fix），保证零功能损失——这是 skill-surface-consolidation.md 反复强调的「every removed micro-skill's behavior survives via a flag」；
2. 同步全部用户可见面：命令文件、agent 角色卡片、命名空间命令路由表、技能文件、核心文档（USER-GUIDE / FEATURES / INVENTORY / AGENTS / CONFIGURATION）、do.md分发表、help 全量文档，一处都不能漏；
3. 禁止影子桩：被删命令必须真实解析为Unknown command，不能留下「假装存在」的占位实现，否则用户会被误导、路由表会腐化；
4. 就地记录迁移原因：在路由表附近用注释写明「某某命令被 #2790 合并、由何处替代」，让未来维护者一眼明白；
5. 两层测试护栏收口：注册表级断言保证「删的删了、留的留了」，文件级断言保证「所有引用点同步换新」。

另外值得注意的是，这一清理不是孤例。CHANGELOG 显示plan-milestone-gaps.md与discovery-phase.md这两个「随运行时发布却从未被加载」的工作流文件随后也被移除（#3560/#3564），并新增了一条 lint 规则：任何随包发布的工作流一旦变得不可达，构建直接失败。这与「Unknown command 零残留」的目标同源——命令表面必须始终与注册表一致。

小结

/gsd-code-review-fix与/gsd-plan-milestone-gaps的「Unknown command」问题，本质是命令合并后 offer 文本滞后于注册表的典型事故。PR #3029 的清理覆盖了审计、里程碑收尾、评审、agent 卡片与五份核心文档的全部可见面，而 docs-parity-live-registry.test.cjs 与 skill-manifest.test.cjs 等测试则把「陈旧命令零残留」从一次性修复固化为持续回归契约。对使用 GSD 的团队而言，这套「合并 → 全表面同步 → 注册表断言」的流程，正是维护一套稳定、可被 Agent 正确调用的命令体系的关键实践。