【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本篇技术文章围绕 gsd-core 归档 changeset.changeset/archived/witty-bears-climb.mdPR #3763展开剖析一次典型的「分支逻辑双路径漂移」修复SDK 侧提交处理器此前未在首次提交前切换到策略分支导致branching_strategy: phase/milestone配置下的 pre-execution 提交落在错误分支上。读完本文你将理解 gsd-core 中branching_strategy的完整机制、CJS 路径src/commands.cts的 create-and-switch 语义与防护条件以及基础分支解析器src/git-base-branch.cts的决策阶梯。一、背景branching_strategy与策略分支gsd-coreGit. Ship. Done - Core以「阶段phase/ 里程碑milestone」为工作单元组织项目推进。当项目选择策略分支工作流时每个阶段或里程碑的工作应累积在专属的 git 分支上而不是全部堆在默认分支base branch上。该行为由git.branching_strategy配置项控制可取值与完整相关配置见 docs/CONFIGURATION.md配置项类型默认值说明git.branching_strategyenumnonenone、phase或milestonegit.base_branchstringmainphase/milestone 分支的创建来源与合并目标仓库使用master或发布分支时需覆盖git.phase_branch_templatestringgsd/phase-{phase}-{slug}phase 策略的分支名模板git.milestone_branch_templatestringgsd/{milestone}-{slug}milestone 策略的分支名模板git.create_tagbooleantrue里程碑完成时创建v[X.Y]标签git.protected_branchesarray(none)除解析出的基础分支外额外触发保护分支警告的共享分支名git.allow_default_branch_commitsbooleanfalse逃生阀#3819为true时允许在解析出的默认分支上提交典型的策略分支配置如下{ git: { branching_strategy: phase, base_branch: main, phase_branch_template: gsd/phase-{phase}-{slug}, milestone_branch_template: gsd/{milestone}-{slug} } }二、回归PR #1279 的分支逻辑只落在 CJS 路径归档 changeset 原文明确记录了问题本质SDK commit handler now switches to the strategy branch before the first commit— fixes the regression where PR #1279s branching logic only landed in the CJS path; pre-execution commits withbranching_strategy: phaseormilestonewere landing on the wrong branch.两个关键信息PR #1279 引入了分支逻辑但实现只落在 CJS 路径即gsd-tools query commit对应的src/commands.ctsSDK 侧的提交处理器没有同步形成双路径漂移——这与仓库反复出现的「修复只落在一边」的 drift bug 类同ADR-3524 中列举了 #1535、#2047/#2052、#2638/#2655 等同类问题见 docs/adr/3524-cjs-sdk-hard-seam.md。受影响的是 pre-execution 提交。所谓 pre-execution指discuss、plan、research等执行阶段execute-phase之前的流程。这些流程也会提交规划产物plan 文档、研究记录等而策略分支此前只在 execute-phase 才创建——正如src/commands.cts第 2047-2049 行的注释所言Pre-execution workflows (discuss, plan, research) commit artifacts but the branch was previously only created during execute-phase — too late.src/commands.cts症状在branching_strategy: phase或milestone的项目中阶段开始前的提交如*PLAN.md、研究产物被提交到了基础分支上而不是对应的gsd/phase-N-slug/gsd/milestone-slug策略分支导致阶段工作分散在两处、分支历史不完整。三、修复SDK 提交处理器首次提交前切换PR #3763 的修复方式是让 SDK 提交处理器与 CJS 路径保持一致在第一次策略作用域提交前切换到策略分支。changeset 将其标记为type: Fixed是对 CJS/SDK 双路径一致性的补齐。CJS 侧对应的既有实现位于 src/commands.cts 的gsd-tools query commit提交命令中其核心流程为读取配置中的branching_strategy若为none或缺失跳过分支逻辑直接提交根据策略解析分支名phase从待提交文件路径中提取阶段编号经detectPhaseNumberFromFiles与项目代码感知的extractPhaseToken处理再经renderPhaseBranchName套用phase_branch_template999.x/0.x积压哨兵backlog sentinel被视为非真实阶段不触发分支变更#3734milestone从里程碑信息解析版本号套用milestone_branch_template若当前分支与解析出的策略分支不同进入创建/切换判定。四、机制深挖create-and-switch 的三重防护策略分支的创建并非无条件进行src/commands.cts中保留了经过多轮回归打磨的防护语义L2124-2210理解它们是理解本次修复的关键#1278 意图restore在分支的第一次提交前创建并切换使阶段工作累积在该分支上#3079 防护已存在的策略分支永远不静默切换——git checkout -b同时创建并切换 HEAD会「复活」已合并并删除的旧阶段分支、把 HEAD 移到过期 ref 上#2539 AC2提交中途的自动 checkout 绝不允许静默发生。因此对已存在分支只警告并在当前分支提交#4055 state-3 判别仅凭git rev-parse --verify refs/heads/branch无法区分「分支从未存在」应创建#1278 意图与「分支存在过、已合并后被删除」阶段已结束重建会劫持收尾提交。因此新增了两重追加条件phase 策略下检查该阶段目录在当前提交线上是否已有提交历史git log HEAD --oneline -- phaseDir两种策略均检查当前分支是否为解析出的基础分支通过resolveBaseBranch见下文。只有通过全部判别、确认为「全新阶段 位于基础分支」时才执行git checkout -b branchName创建并切换并在 stderr 输出明确日志#3207 AC3phase branch gsd/phase-07-... created; switched to it for this commit.任何不满足条件的情形分支已存在、阶段目录已有历史、当前分支非基础分支、创建失败都会输出带原因的警告并在当前分支就地提交绝不静默。五、基础分支解析src/git-base-branch.cts 的决策阶梯create-and-switch 判定依赖「基础分支」这一权威结论。gsd-core 将其收敛到单一解析器 src/git-base-branch.cts取代了此前各工作流重复的 bash 检测只查refs/remotes/origin/HEAD再硬编码:-main会在 CI 检出等场景静默返回错误的main。resolveBaseBranchDiagnostics遵循五级优先级阶梯最高到最低git.base_branch配置覆盖来自.planning/config.jsongit symbolic-ref --short refs/remotes/origin/HEAD快、无网络git remote show origin的HEAD branch:行权威origin/HEAD 未设置时生效解析(unknown)视为不可靠并继续下探本地分支存在性判定有master无main→master有main→main兜底默认main。每个 git 子进程都带超时上限≤30s超时/失败时优雅降级到下一级函数永不抛异常src/git-base-branch.cts。该模块还区分已验证与未验证的兜底结果#3057 B4若第 5 级兜底是因为某次 git 查询超时/无法运行才到达的verified为falsecmdGitBaseBranch --is-protected在此情形下fail-closed——报告true受保护而非信任未经验证的猜测src/git-base-branch.cts。这一行为由 tests/git-base-branch.test.cjs 中的回归测试覆盖#3057 B4 与 #3648 Major 用例。六、工作流视角execute-phase 的 handle_branching 分工策略分支的消费端在 gsd-core/workflows/execute-phase.md 的handle_branching步骤中branching_strategy: none读取并执行gsd-core/workflows/execute-phase/steps/protected-branch.mdprotected-branch.md对解析出的基础分支及git.protected_branches中列出的分支给出保护警告但 GSD 仍会在当前分支继续branching_strategy: phase或milestone直接使用 init 阶段预计算的branch_name无需再次推导。而pre-execution 阶段的提交则经由query commit的提交处理器src/commands.cts中本次修复的对应区域提前完成分支切换——这正是 #3763 修复在时间轴上的意义分支在第一次提交而非 execute-phase之前就位。七、验证与回归防线本次修复有清晰的验证与回归防线CJS 路径行为CHANGELOG 中branching_strategy: phase/milestone条目记录了gsd-tools query commit恢复 create-and-switch 的完整语义#3207/#3363明确「全新分支创建并切换、已存在分支只警告不切换、首次创建输出 stderr 日志」CHANGELOG.md基础分支解析tests/git-base-branch.test.cjs 覆盖resolveBaseBranchDiagnostics的 verified/unverified 区分#3057 B4、--is-protected的 fail-closed 行为#3648 Major以及各级 git 命令的注入式单元测试SDK 路径一致性PR #3763 的 changeset 本身就是 SDK 提交处理器与 CJS 语义对齐的验收记录——首次提交前切换到策略分支与src/commands.cts的 #1278 意图一致。八、总结PR #3763 是一次典型的跨运行时一致性修复分支逻辑PR #1279 引入只落在 CJS 路径而 SDK 提交处理器缺失导致 pre-execution 提交落在错误分支。修复让 SDK 侧在首次提交前切换到策略分支与 CJS 路径的 create-and-switch 语义对齐同时完整保留了 #3079不复活已删分支、#4055全新阶段判别与基础分支验证src/git-base-branch.cts的防护体系。对使用者而言关键结论是只要配置了branching_strategy: phase或milestone无论提交经由 CJS 工具还是 SDK 处理器策略分支都会在第一次提交前创建并切换规划阶段discuss / plan / research的产物也会正确落在阶段分支上。若你维护类似的多运行时CJS/SDK项目本案例可作为「一处功能改动必须双路径同步、并以 changeset 记录一致性修复」的参考模板。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐gsd-core 家族路由器 --raw 标量输出修复解析SDK 分发路径与 CJS 路径的语义对齐gsd core 家族路由器 raw 标量输出修复解析SDK 分发路径与 CJS 路径的语义对齐 本篇技术文章基于 .changeset/archived/fgsd-core 中 config-ensure-section 的 Phase 6 路由迁移兼容性修复CJS 回退路径与 SDK 对齐实践gsd core 中 config ensure section 的 Phase 6 路由迁移兼容性修复CJS 回退路径与 SDK 对齐实践 导读 本文围绕gsd-core 更新补丁重放修复/gsd-update --reapply 排除过滤器与安装器提交误判问题详解gsd core 更新补丁重放修复 /gsd update reapply 排除过滤器与安装器提交误判问题详解 导读 本文围绕 gsd core 仓库中的一个上一篇WeChatMsg技术架构构建个人数据主权的聊天记录管理蓝图下一篇yuzu Switch模拟器上手指南从装环境到跑通第一局的完整路线创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考