用途
bmad-loop-resolve 用于处理 bmad-loop 编排器的「升级解决」环节。一个 bmad-loop 运行把某个故事驱动通过了开发→评审流程后,某个会话提出了 CRITICAL 级升级(工作无法安全继续,通常是冻结规格中存在矛盾或未回答的问题),编排器因此暂停整个运行等待人工。发起升级的会话已经结束;本技能是一个新开的交互式会话,职责是与人工一起解决歧义、更新冻结规格,好让编排器重新武装该故事并针对修正后的规格重新驱动。
这是交互式流程:现场有人类参与。可以提问、给出选项、提出建议,但决定由人类做出。此会话中 $BMAD_LOOP_MODE 故意未设置,从不提问的自动化规则不适用。
输入与环境
会话会设置以下环境变量:
$BMAD_LOOP_RUN_DIR:被暂停运行的目录。$BMAD_LOOP_STORY_KEY:被升级的故事键(同时也是调用参数)。$BMAD_LOOP_RESOLVE_CONTEXT:为本会话写好的 context.json 路径。
会话应先读取 $BMAD_LOOP_RESOLVE_CONTEXT。其结构包含 story_key、run_id、project_root、code_root、spec_file、spec_reaches_the_redrive、redrive_base_ref、baseline_commit、paused_reason、escalations 数组、resolution_path,以及在 stories 模式下附带的 stories 块(含 sentinel 子块)。escalations 按最新在前排序,整个上下文中每个不同的升级只出现一次。
交互式会话的工作目录始终是 project_root,其中存放 BMAD 工件与规格;code_root 是运行的代码与 git 工作所在树,两者可能不同。roots 不同时不要把会话 cwd 误当成代码检出:任何需要人工做的代码修复或提交都属于 code_root,而工件与规格工作仍以 project_root(或上下文中给出的绝对路径)为锚点。本解决会话仍不实现也不提交代码,只在指导人工时指明正确的树。
处理流程
- 读取上下文,然后完整读取 spec_file 处的冻结规格,尤其是其中的
<frozen-after-approval>块(开发/评审会话视为权威的意图)。升级几乎总是因为该块对实现遇到的某个情况沉默或与之矛盾。 - 向人类清晰呈现当前暂停证据:escalations 非空时按已有的最新在前顺序呈现记录条目,不得用 paused_reason 替代记录的升级细节;escalations 为空时,先要求 paused_reason 是至少含一个非空白字符的文本,否则报告解析上下文格式错误且不写解决标记,满足则逐字呈现 paused_reason 作为现有证据,并说明没有更新的已记录升级细节。不得读水位线以下的内容、不得过滤或恢复更旧的工件升级、不得由 paused_reason 合成升级对象。
- 基于所选证据解释哪里歧义或矛盾、为何阻碍安全实现,并给出 2–4 个具体解决选项、明确推荐及取舍,引用相关规格行。
- 取得人类决定;若选择不清可追问,不臆造需求,人类不确定时帮助其推理而非猜测。
- 更新冻结规格,明确编码该决定:修改
<frozen-after-approval>块及受影响的验收标准/测试矩阵行,使新的开发会话只有一个正确解读,做消除歧义的最小改动;更大改动可调用 bmad-spec 或 bmad-correct-course 技能。若 spec_reaches_the_redrive 为 false,做同样修改,然后明确告知此副本不是重驱动读取的那份,并说明 redrive_base_ref 选择的补救方式:为分支名时,修正必须在 redrive_base_ref 上提交;为 HEAD 时,必须在主检出中重新应用且不提交——此处未落地的修改是丢失的工作,在错误树或错误分支上提交是看起来完成了的丢失工作。 - 在 resolution_path 写出解决标记(含 story_key、decision、spec_file、spec_updated,可选 restore_patch),然后告知人类解决已记录、可退出会话,编排器会提供重新武装故事并恢复运行(针对修正规格的干净重建)。
特殊情形
- 评审阶段意图缺口且存有补丁:当升级来自评审步骤因意图缺口而中止,开发会话会先把尝试的改动保存为补丁文件再回退。先检查上下文中的 restore_supported,为 false 时(worktree 隔离运行、无记录规格的升级、规划前哨兵卡死)绝不提供恢复选项、绝不记录 restore_patch。补丁可作证据:读取补丁看猜测性解读产生了什么;当尝试的解读实际正确时,可作为显式选项呈现——仍需在规格中明确写成该解读,并在 resolution.json 加 restore_patch,不要自己 git apply,也不要设置规格 status,编排器会在重新武装时确定性完成。恢复不得与解决提交重叠:若本会话的提交触及补丁自身文件,恢复的 git apply 会失败并使故事再次升级;若解决工作已包含或取代尝试的改动,则省略 restore_patch。尝试解读错误(常见情况)时完全省略 restore_patch。
- Stories 模式下的哨兵文件:故事甚至无法规划(开发会话在写出真正规格前撞上矛盾或缺口)时会留下固定 slug 的哨兵文件
<id>-unresolved.md(意图过于模糊无法规划)或<id>-ambiguous.md(多个故事规格匹配该 id),上下文 stories.sentinel 块会指明它并带有 blocking_condition。哨兵不是可编辑的规格,其中没有计划或<frozen-after-approval>块,因此第 4 步的「编辑冻结规格」不适用;应解决上游歧义以便新的规划通过成功,通常意味着与人类一起厘清 SPEC.md(史诗规格)或 stories.yaml 中该故事的条目(规划器读取的标题/描述/invoke_dev_with)。redrive_base_ref 决定该上游编辑落地位置:为分支名时,重驱动会从该分支的已提交树重新规划,未提交的编辑不可见且会再次生成同样的哨兵,需告知人类在该分支上提交;为 HEAD 时,重驱动在主检出的工作树中重新规划,编辑按原样读取,不要让其提交。重新武装时编排器不会把哨兵翻转为 ready-for-dev,而是在{run}/sentinels/<id>-<kind>.md保留副本、删除哨兵,下一次调度从头重新规划该故事。不要自己触碰哨兵文件。人类决定消歧方式后照常写解决标记,spec_file 设为所编辑的文件(如 SPEC.md),若修复完全在 stories.yaml 中则省略。 - 非哨兵的多文件匹配:当 stories/ 中有多个文件匹配
<id>-*.md(如 3-login.md 与 3-signup.md),id 在磁盘上本身就有歧义,编排器在不选任一文件的情况下卡住故事,可通过升级原因(ambiguous story file match: <names>)以及上下文缺失 stories.sentinel 块和单一 spec 路径来识别。自动清理不适用,因为没有哨兵可保留和删除,仅重新武装只会再次卡在相同重复文件上。解决本身就是清理:与人类决定哪个文件是该故事的真实规格,移除或重命名其余文件(若两者都有真实工作则先合并内容;重命名须移出<id>-*模式或改到另一 id)。恰好一个匹配会重新调度该规格,零匹配会从头重新规划。之后照常写解决标记,重新武装与恢复接管后续。
限制
不得写编排器的 result.json(那是开发/评审工件);不得修改 sprint-status.yaml,也不得设置规格的 status 字段(编排器会在恢复时确定性重新武装);不得实现故事、写功能代码、跑测试或提交——工作止于修正规格与解决标记,spec_reaches_the_redrive 为 false 时同样如此,把修正规格放到重驱动读取的位置是人类的步骤;不得扩大范围,只解决被升级的歧义,发现无关问题告知人类但别动它们。