build-executor

构建执行器

内置运行时

执行下方的 CLI 命令行之前，将其开头的 SSF 替换为 node "<plugin-root>/scripts/spec-superflow.mjs"；<plugin-root> 是此文件向上两级的绝对目录。切勿直接运行 SSF，也不要调用 PATH 中的 ssf。

对于 workflow_variant planned，只读取生成的执行计划和当前任务；审批已包含在计划中。修改代码前运行 SSF isolate <change-dir>，默认使用功能分支。无需合约、建议或 DP-4。对于其他路径，先读取工作流收据。Full/legacy Hotfix 需要已批准的执行合约；仅为当前任务读取关联的需求/设计。Quick/direct Hotfix/Tweak 使用其限定范围的请求和验证策略。Lightweight 遵循其收据中针对重点审查和验证的要求。

预检

Legacy Full/Hotfix 在修改前运行 SSF isolate <change-dir>，并在每条命令中使用返回的绝对检出路径。默认在当前检出中使用功能分支；仅当用户明确选择 --worktree 时才创建工作树。在受保护分支中，隔离失败会阻止修改；保留现有隔离状态，并诊断初始化失败。直接路径无需隔离或实际收尾。

对于 legacy Full，遵循 DP-3 审批。如果缺少记录，但用户已在对话中明确批准了这份确切合约，则记录该既有决定并继续。切勿推断用户已批准未见过或已更改的行为，也不要再次请求对同一份未更改的内容进行审批。仅在计划有效且守卫检查通过时进入 executing；如果已处于该状态，则跳过状态转换。

优先采用原生执行

原生执行是指当前 Agent 持续实现；持久化模式为 inline。任务数、文件数和工作波次数都不足以构成委派的理由。batch-inline 仍与串行执行兼容。仅当用户明确选择为此变更进行委派，且独立限定范围的工作确有具体收益时，才选择 SDD。工具可用、任务众多、上下文较长或泛化的实现审批，均不能授权使用子 Agent。这也包括审查和探索性子 Agent。

仅适用于 legacy 计划（新的 planned 变更已包含其计划）：

SSF execution recommend <dir> --wave <id>:serial:<task,...>[:<dependencies>] --json
SSF execution plan <dir> --mode inline --review-policy final --confirm --reason "<authorized choice>" --wave <id>:serial:<task,...>[:<dependencies>]

沿用用户已有的模式选择。对于非推荐选项，添加 --acknowledge-recommendation。新的 Native 计划默认采用 final 审查；SDD 默认采用 wave 审查。对于明确的风险边界，可使用 --review-policy wave。没有策略的旧计划仍须履行 wave 审查要求。模式与审查粒度彼此独立。

使用 SSF execution show <dir> --json 来厘清不确定性、中断和修复状态，不要把它当作每次修改前的例行步骤。Native wave 的依赖项是已完成的任务；已勾选的任务不能替代对整个范围的最终审查。

一次有限范围的预检

首次修改前，仅检查已批准任务所依赖的共享生产者/消费者接口和测试入口。确认能找到指定的符号、负载字段和验收测试。在现有进度条目中记录不匹配之处；在已批准的行为范围内解决实现细节。仅当解决不匹配会改变行为、范围、权限或外部影响时才询问。不要为此检查派遣探索 Agent，也不要另建规划包。

实施循环

1. 按依赖顺序实施任务。Full／legacy Hotfix 使用失败的行为回归测试，确认 RED，进行最小修复，然后确认 GREEN。文档变更使用格式、链接和构建检查，不要编造单元测试。
2. 每项任务运行受影响的测试，在有意义的边界运行集成测试，并在最终代码快照上运行所需的完整检查。只有代码、环境和命令均相同时才可复用结果；变更会使受影响的证据失效。
3. 标记已完成的任务，并附上一条简短的进度记录：结果、文件／提交、验证、下一步、未解决的风险。不要为每项小任务都创建任务簿、交付报告和检查点。中断或长时间运行的工作需要恢复时，保存 SSF checkpoint save。
4. 在已授权任务之间继续执行，无需请求许可。待处理任务或评审不是结束控制器轮次的理由。复用现有授权；不要为下一个已授权任务询问“是否继续？”。简要说明进度；不要承诺在后台自主执行。

对于新的直接／计划变更，诊断正在执行中的常规缺陷：复现、追踪原因、修复并验证。不要另行创建状态转换、任务报告或调试记录。只有在没有新的有效方法且同一问题仍未解决时才升级。现有的 legacy 变更可以进入 debugging 并使用 bug-investigator。预期的 RED 是测试证据，不是意外缺陷。范围变更将 Full 回退到 specifying；契约偏移将回退到 bridging。简短路径应刷新其风险凭证，而不是凭空编造契约。

选择不确定的测试证据时，阅读 SSF runtime asset read skills/build-executor/writing-good-tests.md。

评审

对于 Native final，当前执行器应在实施和所需测试完成后进行一次覆盖整个范围的评审，检查规范符合性和代码质量。不要启动 reviewer 子 Agent。提交代码，并将报告关联到其实际 Git 范围。通过以下方式记录：

SSF execution review <dir> --wave final --base <base-sha> --head <head-sha> --report .superpowers/sdd/reviews/final.md --verdict <pass|fail>

对于 wave，每个计划波次评审一次，使用其 ID 而不是 final；依赖项必须有当前通过的凭证。SDD 可以在每个波次使用一个 reviewer 子 Agent，因为用户已授权委派。不要为每项任务和最终阶段重复评审。Critical／Important 发现必须经过失败 → 定向修复 → 一次定向复审 → 通过。

重试前先读取 CLI 修复状态。切勿编辑修复状态文件。在新计划中，为失败的评审记录稳定的 --issue <finding-id>，并对同一未解决缺陷沿用该 ID。该问题失败三次后须由人工裁定；不同发现不共用次数额度。Legacy 计划沿用其记录的总次数额度；SSF execution adjudicate <dir> --wave <id> --decision allow-review --confirm --reason <text> 授权再进行一次评审，但绝不代表通过。保留先前的评审头，以确保修复范围连续。最终评审需要时，应重新评审原始完整范围及修复内容，以认证最终快照。

可选 SDD

仅在选择 SDD 时加载分派材料。仅当某个工作波次进入审查阶段时，才加载审查员提示词：

• SSF runtime asset read skills/build-executor/implementer-prompt.md
• SSF runtime asset read skills/code-reviewer/code-reviewer-prompt.md

仅发送任务目标、限定文件、接口、相关需求 ID 和测试命令。对于针对性修复，复用同一实现者；不得进行嵌套委派，也不得重复发送完整规划资料包。将密切相关的小任务合并处理。仅在支持并发且任务相互独立时并发分派；否则说明限制并按顺序执行。

配置档案：mechanical、standard、strong、review。每种角色仅执行一次 SSF runtime config --resolve-model <profile>。如果支持，则传入已配置的模型。如果 configured: false，则沿用宿主模型；不要臆造模型或阻止执行。仅在有新证据、上下文或策略时重试受阻的工作；三次尝试后仍未解决，则使用 DP-5。

计划修正与完成

非语义性的计划修正使用 SSF execution resync <dir> --confirm --reason <text>，包括修复链仍处于开放状态时；历史记录和失败次数仍具有约束力。语义范围变更需要重新审批并执行 execution revise。修订可以保留或更改已授权的模式。旧回执仍保留为历史记录，且不会自动证明范围已变更或新的最终快照已获认证。

完成前，须满足合约义务、测试要求和计划中的审查政策。必要时记录 batches_completed。对于新的直接变更或计划内变更，使用带有最终验证命令的 workflow complete；对于旧版变更，则转交 release-archivist。合并、推送或发布均须获得各自现有的授权。

Quick/direct Hotfix 在限定范围的验证后持久化 test_result: pass；Hotfix 必须证明原始问题已修复。它们不需要 DP-4、执行计划、工作波次回执、DP-6 或 DP-7。Lightweight 还须持久化回执要求的针对性审查和通过的命令。

Quick 遵循其回执中持久化的验证策略。Tweak 跳过 TDD。Full 和 legacy Hotfix 使用 RED → GREEN → REFACTOR。