get-shit-done 修复 3599 深度解析：roadmap get-phase 如何正确命中 project-code 前缀阶段 ID

本文基于仓库中的变更记录 .changeset/3599-roadmap-get-phase-project-code-prefix.md，讲清 get-shit-done（GSD 元提示与规格驱动开发系统）中 roadmap get-phase 子命令的一个正则匹配缺陷及其修复方案：当阶段 ID 带有项目代号前缀（如 PROJ-42）时，命令曾查不到 ROADMAP.md 中真实的 ### Phase PROJ-42: 标题。读完本文，你能理解该命令背后的“两遍查找（two-pass）”设计、phaseMarkdownRegexSourceExact() 新辅助函数的职责边界，以及它与历史修复 #3537、#2391 之间如何互相保约而不互相破坏。

背景：GSD 的阶段 ID 体系与 ROADMAP 散文解析

get-shit-done 以 .planning/ROADMAP.md 作为项目规划的单一事实来源，阶段以 Markdown 标题形式书写，形如 ### Phase 2.7: 功能名。解析阶段标题的入口是 get-shit-done/bin/lib/roadmap.cjs 中的 cmdRoadmapGetPhase，它把「调用方传入的阶段 ID」转换成一段正则片段，再拼进 #{2,4}\s*Phase\s+<片段>:\s*([^\n]+) 这样的标题匹配模式中。

问题在于，阶段 ID 存在多种合法形态。从 核心库 的 normalizePhaseName() 可以看出系统支持的输入：

• 标准数字阶段：1、01、12A、12.1（整数部分可补零、可带字母后缀、可带小數位）；
• 带 project-code 前缀的目录名形态：CK-01-name（project_code 配置会出现在阶段目录名中）；
• 自定义阶段 ID：PROJ-42、AUTH-101（normalizePhaseName 对这类非数字 ID 原样返回）。

其中两类形态之间天然存在「错位」：

1. 补零错位（#3537 / #2391）：skill 或 CLI 解析后传入补零形态 02.7，而人类手写的 ROADMAP 惯用未补零的 ### Phase 2.7:。为此，core.cjs 提供了 phaseMarkdownRegexSource()：先剥掉 project-code 前缀，再把整数部分的 leading zero 去掉、重新以 0* 前缀输出，使片段同时匹配 2.7 与 02.7。其源码注释明确记录了动机：

function phaseMarkdownRegexSource(phaseNum) {
  const stripped = String(phaseNum).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
  const match = stripped.match(/^0*(\d+)([A-Z])?((?:\.\d+)*)$/i);
  if (!match) return escapeRegex(phaseNum);
  const integer = match[1].replace(/^0+/, '') || '0';
  const letter = match[2] ? escapeRegex(match[2]) : '';
  const decimal = match[3] ? escapeRegex(match[3]) : '';
  return `0*${escapeRegex(integer)}${letter}${decimal}`;
}

2. 前缀错位（本次 #3599）：PROJ-42 这类 ID 本身就是一个自定义阶段 ID，ROADMAP 里真实写的是 ### Phase PROJ-42:。但上面的 phaseMarkdownRegexSource() 会先剥掉 PROJ- 前缀再生成 0*42——于是 roadmap get-phase PROJ-42 实际生成的正则是 0*42。

缺陷机理：剥前缀后的正则丢失了「精确身份」

用 0*42 这段片段去匹配 ROADMAP 时会出现两种坏结果（回归测试文件 tests/bug-3599-roadmap-get-phase-project-code-prefix.test.cjs 头部注释对此有完整描述）：

• 若 ROADMAP 里只有 ### Phase PROJ-42: 而没有 ### Phase 42:，0*42 匹配不到任何标题，命令返回 found: false——变更记录里描述的行为就是「roadmap get-phase PROJ-42 now matches ### Phase PROJ-42: instead of returning found: false」；
• 若 ROADMAP 里恰好还有一个同尾数的裸数字标题 ### Phase 42:，0*42 会交叉命中它，把属于 42 的阶段内容错配给 PROJ-42 查询。

还有一个微妙的实现陷阱：phaseMarkdownRegexSource() 的 docstring 承诺「对非数字 ID 回退到 escapeRegex(phaseNum)」，但剥前缀之后 PROJ-42 变成了纯数字 42，if (!match) 这个回退分支对项目代号前缀 + 数字的 ID 而言永远不可达——承诺的 fallback 恰好覆盖不到最需要它的输入。

修复方案：新增精确形态辅助函数 + 调用点两遍查找

修复分两层，且刻意把「选哪种正则」的决策放在调用点而非正则内部。

第一层：phaseMarkdownRegexSourceExact()——只回答「有没有前缀」

新辅助函数位于 core.cjs，实现极短：

function phaseMarkdownRegexSourceExact(phaseNum) {
  const raw = String(phaseNum);
  if (!/^[A-Z]{1,6}-(?=\d)/i.test(raw)) return null;
  return escapeRegex(raw);
}

语义：

• 输入形如 PROJ-42（1~6 位大写字母 + 连字符 + 至少一位数字开头）时，返回整体转义后的精确片段 PROJ\-42，用于匹配 ### Phase PROJ-42: 这一保留前缀的标题；
• 输入不带前缀（如 42、02.7、12A.1）时返回 null，表示调用方只需要既有的 phaseMarkdownRegexSource() 数值形态即可。

这样把「是否需要精确前缀匹配」的判定与「数值补零容忍」的片段构造解耦，phaseMarkdownRegexSource() 的 #3537 契约保持原样，所有既有调用方零改动。

第二层：cmdRoadmapGetPhase 的两遍查找

修复后的命令实现见 roadmap.cjs。查找顺序是：

1. 精确前缀遍：若 phaseMarkdownRegexSourceExact(phaseNum) 非 null，先用精确片段搜索「当前里程碑切片」（extractCurrentMilestone 产出的内容），未命中再搜索剥离已交付里程碑后的全量 ROADMAP（stripShippedMilestones）；
2. 补零容忍遍（#3537）：只有精确遍落空，才用 phaseMarkdownRegexSource(phaseNum) 生成 0*42 形态片段，按同样的「当前里程碑优先、全量兜底」策略搜索。

源码中的注释解释了为什么不在正则内部用「PROJ\-42|0*42」这样的选择式一步完成：

Doing this at the call site (instead of inside phaseMarkdownRegexSource) avoids the alternation-order ambiguity where a bare ### Phase 42: heading in the same document would intercept the match for a PROJ-42 query.

即选择式正则的匹配顺序会让同文档中的裸 ### Phase 42: 标题拦截掉 PROJ-42 查询；两遍查找则保证「先精确、后宽松」的优先级在逻辑上成立，同时不破坏 CK-01 目录名形态映射到 ### Phase 1: 散文的既有契约。

命中之后的输出结构

无论哪一遍命中，最终都交给 searchPhaseInContent() 解析出结构化结果：匹配 ##～#### 级标题并截取到下一个阶段标题之间的区块，提取 **Goal:**、**Mode:**（统一小写后规范化）与 **Success Criteria** 编号列表，返回：

{
  found: true,
  phase_number: phaseNum,   // 标题中「如所写」的规范 token
  phase_name,               // 标题冒号后的名称
  goal, mode,
  success_criteria,         // 字符串数组
  section,                  // 完整章节原文
}

另有两条兜底路径：标题缺失但概要清单里存在 - [ ] **Phase X:** ... 时，返回 error: 'malformed_roadmap' 提示 ROADMAP 需要「清单 + 详情节」双格式；ROADMAP.md 不存在时返回 { found: false, error: 'ROADMAP.md not found' }。加 --json 参数即输出上述 JSON payload，这正是回归测试断言的字段（found、phase_name、goal）。

SDK 侧的镜像实现

该仓库同时维护一套 TypeScript 的 SDK 查询层，roadmap.get-phase 在 sdk/src/query/roadmap.ts 中作为 roadmapGetPhase 处理器存在，是 cmdRoadmapGetPhase 的移植版本（源码注释标注 "Port of cmdRoadmapGetPhase from roadmap.cjs lines 75-113"）。#3599 的修复在 SDK 侧保持了逐行对等（parity）：

• phaseMarkdownRegexSourceExact() 与 core.cjs 版本逐语句一致，注释直接写明「parity with core.cjs phaseMarkdownRegexSourceExact, lines 691-708」；
• roadmapGetPhase 内部同样先计算 exactEscaped（精确前缀片段）与 numericEscaped（phaseMarkdownRegexSource 片段），先试精确片段、落空再走补零容忍片段，且都遵循「当前里程碑切片 → 全量内容」的两级搜索。

另外，CLI 侧的子命令路由在 roadmap-command-router.cjs 中把 get-phase 转发到 SDK 处理器 roadmap.get-phase——也就是说路由层与底层解析层的两条实现在同一个语义下工作，修复对两条链路同时生效。

回归测试：四个用例钉死四种行为

tests/bug-3599-roadmap-get-phase-project-code-prefix.test.cjs 基于 node:test，通过 runGsdTools() 在临时项目中真实执行 roadmap get-phase ... --json，四个用例分别覆盖：

1. 正向命中：ROADMAP 只含 ### Phase PROJ-42: Custom phase，查询 PROJ-42 必须 found: true，且 phase_name / goal 与该标题一致；
2. 反向不交叉：查询裸 42 时，绝不能命中 ### Phase PROJ-42:（防止修成「双向交叉匹配」）；
3. #3537 契约保持：查询 CK-01（project-code 前缀 + 补零）时，仍须解析到未补零的 ### Phase 1: 散文——证明新修复没有弄丢旧契约；
4. 双形态共存消歧：同一 ROADMAP 同时存在 ### Phase 42: 与 ### Phase PROJ-42: 时，两个查询各自命中自己那条。

这四个用例合起来构成一个完整的「不回归、不交叉、能消歧」矩阵，在本地可用 node --test tests/bug-3599-roadmap-get-phase-project-code-prefix.test.cjs 直接复验。

修复的定位与适用前提

• 契约关系：#3599 是在 #3537（phaseMarkdownRegexSource() 补齐到全部 8 个正则构建点，见 变更记录）的基础上，把「前缀保留」这一维度从正则内部剥离到调用点，两条契约（前缀 ID 精确匹配 / 目录补零形态映射数字散文）各自独立可验证；
• 适用前提：该修复在仓库中以待发布的 changeset 形式存在（type: Fixed, issue: 3599），适用对象是配置了 project_code、ROADMAP 中使用 ### Phase PROJ-42: 这类带前缀标题的项目；对纯数字阶段与无 project-code 的项目行为不变（phaseMarkdownRegexSourceExact() 对无输入返回 null，直接走原路径）；
• 相关变更：同批 changeset 中的 3600-milestone-phase-filter-project-code.md 处理的是 milestone 阶段过滤侧的同类前缀问题，与本篇的 get-phase 查找侧互为补充。

小结

#3599 修复看似只涉及一个正则片段，实际示范了一套处理「多形态 ID 命名空间」的可复用模式：用一个廉价的判别函数（phaseMarkdownRegexSourceExact()，仅判断前缀存在性）把「精确形态」与「宽松形态」的正则构造拆开，再由调用点按「先精确、后宽松」的顺序做两遍查找，从而同时满足新契约（PROJ-42 → ### Phase PROJ-42:）、旧契约（CK-01 → ### Phase 1:）和消歧要求（42 与 PROJ-42 互不串扰），并在 CLI 与 SDK 两套实现中保持逐行对等。对于同样以 Markdown 散文承载结构化状态（ROADMAP、STATE 等）的规格驱动工具链，这种「判别 + 两遍查找 + 双向回归用例」的做法值得直接借鉴。