gsd-core 里程碑归档目录解析修复：getActiveMilestoneArchiveDir 的 null 语义与 W007 误报消除

【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本文聚焦 gsd-core 中一个里程碑生命周期上的关键修复PR #416当活动里程碑尚无归档目录时getActiveMilestoneArchiveDir不再回退到最新归档目录而是返回null从而在 flat→archive 过渡期间彻底消除验证器verifier把先前里程碑的阶段误报为活动的 W007 误报。读完本文你将理解 gsd-core 的里程碑归档目录解析规则、W007 诊断的判定数据源以及该修复对应的三组回归测试场景。背景GSD 的里程碑生命周期与归档目录布局gsd-coreGit. Ship. Done - Core把规划数据组织在项目根目录的.planning/之下。每个里程碑经历两个形态flat 形态进行中当前里程碑的阶段目录直接位于.planning/phases/下例如.planning/phases/01-foundation/archive 形态已归档当milestone complete执行时阶段目录被移动进.planning/milestones/version-phases/例如.planning/milestones/v1.0-phases/01-foundation/同时ROADMAP.md、REQUIREMENTS.md与审计文件也按version-ROADMAP.md等命名归档。这一移动而非复制的语义由 src/milestone.cts 中cmdMilestoneComplete的实现固化归档是不可逆的单向门one-way doormilestone complete version --confirm会把当前里程碑窗口内的阶段目录逐个retryRenameSync到milestones/version-phases/见 src/milestone.cts#L1206-L1226。完整命令参数见 docs/CLI-TOOLS.md#L1021-L1049。问题恰恰出在两个里程碑交替的过渡期milestone complete已经将上一个里程碑归档而新里程碑刚开始或尚未开始此时新里程碑在.planning/milestones/下还没有自己的vX.Y-phases/归档目录。这种状态下解析活动里程碑的阶段归档目录如果处理不当就会污染后续的健康检查。Bug 分析getActiveMilestoneArchiveDir 的错误回退原实现修复前存在一个结构性缺陷当STATE.md中标注的活动里程碑在milestones/下找不到匹配的归档目录时getActiveMilestoneArchiveDir会回退到最新版本号最高的归档目录。从 tests/health-validation.test.cjs 中折叠保留的 bug-416 回归测试注释可以精确还原当时的错误路径Bug: getActiveMilestoneArchiveDir falls back to the newest archive directory when STATE.md names a milestone that has no matching archive yet, producing W007 false positives for phases from a prior (completed) milestone.典型触发场景对应测试 Case 1见 tests/health-validation.test.cjs#L882-L917STATE.md的milestone:字段指向新里程碑v6.0但v6.0尚无归档目录其阶段还在.planning/phases/的 flat 形态下磁盘上存在上一里程碑的归档milestones/v5.0-phases/含阶段 17–22旧的解析逻辑把v5.0-phases/当作活动里程碑的归档目录返回W007 检查磁盘上有阶段目录但 ROADMAP.md 未声明随即遍历该归档里的阶段目录把 v5.0 的阶段 17–22 全部报为孤儿orphan阶段——因为当前 ROADMAP 只声明 v6.0 的阶段 23。结果就是已完成里程碑的阶段在每次validate health时都被误报为活动产生一批无法通过正常手段消除的 W007 噪音。修复方案解析器返回 null而非猜一个最新归档修复后的解析契约非常明确回归测试文件将其概括为 Knuth 式不变式The resolver answers one question — what archive directory holds the active milestones phases? Answer space:dir | null.即解析器只回答一个问题——哪个归档目录存放着活动里程碑的阶段答案空间只有两种目录路径或null不存在。具体决策逻辑见 tests/health-validation.test.cjs#L789-L804 的文档注释当STATE.md存在且可解析且其milestone:字段明确命名了一个版本但milestones/下没有匹配的vX.Y-phases/目录时 → 返回null活动里程碑尚无归档这是 flat→archive 过渡期的正常状态版本号排序回退到最新归档目录的逻辑只保留给STATE.md缺失或不可解析的情况——此时无从得知活动里程碑版本最新归档是唯一合理的近似。这一改动让验证器verifier对活动的定义回归严谨活动里程碑在 flat 形态下其阶段目录只存在于.planning/phases/而先前里程碑的归档目录不应被当作活动内容读取。回归测试三个场景锁定修复语义该修复对应的回归测试被折叠进 tests/health-validation.test.cjs#L780-L1007来源为tests/bug-416-archive-dir-null.test.cjs共三个用例完整覆盖了解析器的答案空间Case 1 — STATE.md 为 v6.0磁盘上只有 v5.0-phases/核心缺陷场景断言validate health --json输出中 W007 数量为 0。v5.0 归档中的阶段 17–22 绝不能作为活动出现即使 ROADMAP 未声明它们。Case 2 — 无 STATE.md磁盘上有多个归档保留旧回退行为断言无 STATE.md 时版本排序回退仍生效解析器返回版本号最高的归档v5.0且该归档的阶段17–19已在 ROADMAP 中声明因此 W007 不触发。这证明修复没有破坏STATE.md 缺失场景下的既有行为。Case 3 — STATE.md 为 v5.0且 v5.0-phases/ 存在快乐路径断言当活动里程碑确有匹配归档时解析器正常返回该目录归档阶段在 ROADMAP 中且被视为活动W007 为 0。这保证修复对正常归档项目零影响。三组用例共同把回退从无条件行为收紧为仅当 STATE.md 缺席/不可解析时才允许是典型的防御性边界收紧。源码纵深W007 为何依赖归档目录解析要理解该修复的价值需要看清 W007 诊断的完整数据流。W007磁盘上有阶段目录但不在 ROADMAP 中的判定实现在 src/health-diagnostic-rules/roadmap-disk-consistency.cts磁盘侧数据源是allPhaseDirNames而非被窗口过滤过的phaseDirs。phaseDirs带inWindow过滤getMilestonePhaseFilter见 src/roadmap-parser.cts#L1898-L2027只会包含 ROADMAP 已声明的阶段若用它做 W007 数据源W007 在结构上就永远查不出孤儿目录。因此 W007 使用snapshot.allPhaseDirNames由 src/planning-snapshot.cts 的buildAllPhaseDirNamesField构建并排除哨兵目录如999-*backlog、0-*草稿见 src/health-diagnostic-rules/roadmap-disk-consistency.cts#L275-L309。归档目录枚举与版本排序由 src/phase-locator.cts 的listArchiveVersionDirs承担单一事实来源它按^v[\d.]-phases$识别归档目录并使用compareArchiveVersionDesc做逐数字段的降序比较v1.10排在v1.9之前而非字典序见 src/phase-locator.cts#L143-L189。这正是最新归档回退所依赖的排序逻辑。归档阶段 tokenW002/W006 的豁免来源由buildArchivedPhaseTokensField提供它镜像verify.cts的forEachArchivedPhaseToken逐目录读取归档下的阶段 token见 src/planning-snapshot.cts#L1039-L1089。值得注意当前 W007 的循环本身只扫描活动phases/根目录从不直接扫描归档目录见 src/health-diagnostic-rules/roadmap-disk-consistency.cts#L53-L55 的说明。但归档目录解析的错误回退之所以仍会造成 W007 误报是因为在修复前的验证器路径中归档阶段的 token 会被并入磁盘上的阶段集合forEachArchivedPhaseToken逐个 token 加入diskPhases一旦 ROADMAP 未声明这些阶段W007 就针对它们开火——这正是 PR #416 消除的误报路径。与此同源的修复还包括 ADR-3524 中W007 改为遍历activeDiskPhases仅来自collectDiskPhases不含forEachArchivedPhaseToken的归档 token的决策见 docs/adr/3524-cjs-sdk-hard-seam.md#L118-L127。如何验证与排查运行健康检查在项目根目录执行node gsd-tools.cjs validate health--repair可选或node gsd-tools.cjs validate consistency。W006/W007 是同一套诊断代码的两个消费者均输出结构化{code, message, fix, repairable}诊断见 docs/CLI-TOOLS.md#L800-L818。人工检查归档状态查看STATE.md的milestone:字段与.planning/milestones/下的目录列表确认活动里程碑版本与存在的version-phases/是否匹配。运行回归测试tests/health-validation.test.cjs中bug #416 case 1/2/3三个 describe 块可直接验证本修复的完整语义。小结PR #416 的修复本质是把活动里程碑归档目录的解析从启发式猜测找不到就取最新改为显式契约找得到返回目录、找不到返回 null。它消除了 flat→archive 过渡期验证器把先前里程碑阶段误报为活动的 W007 噪音同时通过 Case 2/3 保证了无 STATE.md 回退与正常归档场景的行为零回归。对使用 gsd-core 的团队而言这意味着每次milestone complete之后的健康检查输出不再携带历史阶段的幽灵警告validate health的结果可以更可信地作为发布闸门依据。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐gsd-core W002 误报修复详解/gsd:health 为何不再为已归档 Phase 报错gsd core W002 误报修复详解/gsd:health 为何不再为已归档 Phase 报错 本文围绕 gsd core 仓库中的一个变更集记录chaGSD 里程碑阶段过滤器修复解析让 CK-01 前缀阶段目录正确计入数字 ROADMAP 里程碑GSD 里程碑阶段过滤器修复解析让 CK 01 前缀阶段目录正确计入数字 ROADMAP 里程碑 本篇基于 get shit doneGSD仓库中的 ch人工智能AI 应用提示工程开发工具工作流自动化AI Agentget-shit-done /gsd:health 一致性检查归档里程碑阶段引发的 W002 误报3652修复全解析get shit done /gsd:health 一致性检查归档里程碑阶段引发的 W002 误报 3652修复全解析 导读 本文围绕 get shit人工智能AI 应用提示工程开发工具工作流自动化AI Agent上一篇从基础到进阶express-winston日志中间件全方位使用指南下一篇Smartspacer终极指南如何快速安装并自定义你的Android桌面小部件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考