【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载导读本文基于 gsd-core 仓库中已归档的 changeset.changeset/archived/witty-geese-purr.md剖析一次针对阶段目录命名两套体系并存问题的修复当项目在.planning/config.json中配置了project_code后/gsd-discuss-phase与/gsd-plan-phase两条首次触达路径不再生成不带前缀的目录而是与phase.add/phase.insert保持一致的{PROJECT_CODE}-{NN}-{slug}命名。读完本文你将理解project_code前缀在整个阶段目录创建链路中的统一规则、共享 helper 的职责边界、对应的工作流改造与回归测试保障并掌握排查与修复自身仓库中双头目录的方法。一、背景project_code与阶段目录命名规则gsd-core 的规划工作区以.planning/phases/存放每个阶段的目录目录名遵循{NN}-{slug}形态如01-foundation/。当一个仓库需要同时管理多个项目或需要跨项目消歧时可以通过在.planning/config.json中设置project_code为阶段目录名增加前缀{ project_code: XR }配置后阶段目录名变为{PROJECT_CODE}-{NN}-{slug}例如XR-01-foundation/。这一能力在 docs/features/project-code-prefixing.md 中被定义为 v1.31 特性并明确了三条需求约束需求内容REQ-PREFIX-01配置了project_code时阶段目录必须以项目代码为前缀如ABC-01-setup/REQ-PREFIX-02未配置project_code时必须保持标准命名即无前缀的01-setup/REQ-PREFIX-03前缀必须在所有阶段操作中一致应用配置项的完整说明见 docs/CONFIGURATION.md设置类型默认值说明project_codestring无阶段目录名前缀如ABC生成ABC-01-setup/v1.31 新增从 src/phase-id.cts 的注释与实现可以看出project_code遵循[A-Z][A-Z0-9_]*语法允许数字与下划线且不限于 6 位这一形态与配置校验、以及解析路径上用于剥离前缀的stripProjectCodePrefix见 docs/adr/2121-phase-identifier-parsing-consolidation.md保持同一份语法来源。二、问题两条创建路径造成的双头目录2.1 现象描述changeset 原文给出了非常具体的故障画像当project_code已配置时同一仓库的.planning/phases/下会出现两种风格并存的目录名——01-foundation/ # 无前缀由 discuss-phase / plan-phase 首次触达创建 XR-02.1-spike/ # 带前缀由 phase.add / phase.insert 创建这种01-foundation/与XR-02.1-spike/混排的两套命名体系two-headed naming convention会造成阶段目录在解析、归档、状态统计等多个环节的歧义。2.2 成因首次触达路径漏掉前缀/gsd-discuss-phase与/gsd-plan-phase属于首次触达路径——当一个阶段尚未建立目录时由这两条流程负责把目录从无到有创建出来。修复前这两条路径在计算目标目录名时没有套用project_code前缀而phase.add/phase.insert在创建目录时却已经带上了前缀。于是同一条 ROADMAP 上后续追加的阶段带前缀、先前由讨论/规划流程首建的阶段不带前缀目录树便出现了双头。2.3 潜在危害解析歧义目录匹配逻辑如 src/phase-locator.cts 中的searchPhaseInDir/findPhaseInternal依赖目录名的 token 匹配同一裸阶段号可能命中多个目录触发歧义告警源码中会提示 Set a distinct project_code in .planning/config.json to scope resolution见 src/phase.cts。状态漂移验证、UAT、归档等按目录扫描的功能会漏读或重复读到阶段产物。跨项目串扰多个项目共享一个.planning/phases/树时无前缀目录无法归属到正确的项目。三、修复方案把阶段目录创建收敛到共享 helperchangeset 的修复策略很清晰将阶段目录命名与创建统一路由到单个共享 helper当时命名为getPhaseDirName从源头杜绝各调用方各自拼装目录名导致的漂移。在当前仓库中承担这一规范化切点职责的代码可以对应到两处src/phase-id.cts 的getPhaseDirFromPhaseId纯函数式地根据phaseId、阶段名与projectCode生成规范化目录名——零填充的里程碑/阶段号 规范化 slug 可选的项目代码前缀并委托core-utils的共享 slug 生成逻辑避免各调用方重复实现 slug 公式。src/init.cts 中expected_phase_dir的推导cmdInitPlanPhase约 L1210-L1221与cmdInitPhaseOp约 L2304-L2315在阶段目录尚不存在时按同一公式计算出应当存在的目录路径并回传给工作流工作流只需mkdir -p ${expected_phase_dir}即可。3.1 各创建路径的前缀统一现状修复后仓库内所有阶段目录创建入口都遵循{prefix}{NN}-{slug}或{prefix}{NN.MM}-{slug}的同一公式创建入口位置前缀应用phase.addsrc/phase.ctsconst prefix projectCode ? \${projectCode}- : 目录名拼入prefixphase.add-batchsrc/phase.cts同一prefix公式phase.insertsrc/phase.cts_dirName \${pfx}${_decimalPhase}-${slug}含子阶段号如XR-02.1-spikescaffold phase-dirsrc/commands.cts代码注释明确标注#3287应用project_code前缀以与phase.add/phase.insert保持一致init plan-phase/init phase-op的expected_phase_dirsrc/init.cts推导时拼入前缀供工作流首次触达使用可见#3287这条修复不仅覆盖了 changeset 中提到的两条工作流命令还顺带补齐了scaffold phase-dir这一手工脚手架入口形成全链路一致。四、工作流侧配套从mkdir裸拼到expected_phase_dir仅靠命令侧统一还不够——工作流文档中的首次触达步骤此前可能使用裸的mkdir -p .planning/phases/{NN}-{slug}一旦手工拼装就会再次漏掉前缀。修复后工作流统一改为消费 init 返回的expected_phase_dirgsd-core/workflows/discuss-phase.mdFind or create phase directory读取 init 返回的phase_dir、expected_phase_dir、phase_slug、padded_phase当phase_dir为 null 时执行mkdir -p ${expected_phase_dir}然后phase_dir${expected_phase_dir}。gsd-core/workflows/plan-phase.mdphase_found为 false 时先校验 ROADMAP 中存在该阶段再使用expected_phase_dir注释明确说明includesproject_codeprefix when set创建目录。gsd-core/workflows/add-backlog.md先读取project_code再拼接带前缀的 backlog 目录名保持与所有其他阶段创建路径一致。这种让命令计算、让工作流消费的设计把命名规则收敛在单一职责的 helper 中避免了工作流文档各自为政地手写目录名公式。五、测试保障前缀一致性回归套件修复不是孤证tests/phase.test.cjs 中沉淀了完整的回归测试bug-3287 套件tests/phase.test.cjs#L7088-L7252构造project_code: XR的临时项目makeXRProjectfixture断言phase.add生成XR-02-auth-service而非裸02-auth-serviceinit phase-op 1在目录不存在时返回expected_phase_dir且路径同时包含XR-前缀与阶段 slug未设置project_code时expected_phase_dir不得匹配^[A-Z][A-Z0-9]*-前缀形态即保持标准命名对应 REQ-PREFIX-02init plan-phase 1对expected_phase_dir的同一组断言。bug-3298 套件tests/phase.test.cjs#L7255-L7304直接扫描gsd-core/workflows/import.md等工作流文件内容用正则禁止出现裸mkdir .planning/phases/{NN}-{slug}模板与裸 shell 变量拼装模式并要求必须引用expected_phase_dir——把防漂移推进到了文档内容层。这两层测试分别从命令输出正确与工作流文档不再手写裸目录名两个维度锁死了回归。六、实践指南在自己的仓库中检查与落地6.1 检查是否存在双头目录在使用了project_code的 gsd-core 项目中直接查看规划目录ls .planning/phases/如果同时出现01-foundation/无前缀与XR-02.1-spike/有前缀两种形态即命中本文所述问题可进一步通过gsd_run query config-get project_code --raw确认配置值。6.2 如何让后续创建保持一致确保.planning/config.json中的project_code为期望的项目代码如XR阶段目录的创建一律交给命令侧完成使用phase add/phase insert/scaffold phase-dir或在init plan-phase/init phase-op返回expected_phase_dir后由工作流mkdir -p不要在脚本中手工拼装{NN}-{slug}若已存在无前缀的历史目录可将其重命名为带前缀的规范名注意同步更新引用该目录路径的文档与状态使命名收敛到单一体系。6.3 与 bracket 约定的关系project_code前缀是独立于phase_id_convention的维度。即便采用bracket约定标题形如### [GSD.02] 05: Name、目录形如GSD.02-05-namebracket 发射路径也只由config.phase_id_convention bracket门控而非由project_code是否存在门控——详见 docs/adr/612-bracket-phase-id-convention.md。也就是说配置了project_code但未启用 bracket 的仓库同样必须遵守本文所述的前缀一致性规则。七、相关证据与延伸阅读原始变更记录.changeset/archived/witty-geese-purr.mdtype: Fixed关联 PR 3292已归档发布说明中的同源记录docs/RELEASE-NOTES-LEGACY.md标注为 #3287特性规格docs/features/project-code-prefixing.md配置参考docs/CONFIGURATION.md核心实现src/phase.cts、src/commands.cts、src/init.cts、src/phase-id.cts工作流gsd-core/workflows/discuss-phase.md、gsd-core/workflows/plan-phase.md、gsd-core/workflows/add-backlog.md、gsd-core/workflows/import.md回归测试tests/phase.test.cjs关联架构决策docs/adr/612-bracket-phase-id-convention.md、docs/adr/2121-phase-identifier-parsing-consolidation.md小结witty-geese-purr这条 changeset 代表了一类典型的工程治理手段当多个入口各自实现同一命名规则时漂移只是时间问题。gsd-core 的解法——统一共享 helper、命令侧计算期望路径、工作流侧只消费不拼装、测试同时锁定命令行为与文档内容——为project_code前缀的一致性提供了从实现到文档再到回归的完整闭环值得在阅读源码与二次开发时对照参考。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐gsd-core Progress 路由的规划前假设检查统一规范化 /gsd-discuss-phase 替代路径gsd core Progress 路由的规划前假设检查统一规范化 /gsd discuss phase 替代路径 导读 本篇文章以 gsd core 仓库gsd-core 修复 Phase 目录 project_code 前缀漂移3298 让 import 与 backlog 工作流统一遵守目录命名约定gsd core 修复 Phase 目录 project_code 前缀漂移 3298 让 import 与 backlog 工作流统一遵守目录命名约定 本篇gsd-core /gsd-discuss-phase 模式路由修复让 workflow.discuss_mode: assumptions 在 shim-only 安装下也能被正确遵守gsd core /gsd discuss phase 模式路由修复让 workflow.discuss_mode: assumptions 在 shim o上一篇gifuct-js颠覆传统JavaScript GIF解码的终极性能革命下一篇如何快速上手MusePose虚拟人视频生成的终极实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
