comet-build

Comet 第 3 阶段：规划与构建

首次进入某个阶段、移交给新的 Agent，或恢复上下文时，请阅读并遵循任务上下文与产物语言。优先使用当前续接信息或已认领 Action 的 contextRequest；同一阶段内工作未中断时，不要重复获取。

进入阶段后返回布局时，请遵循 comet-classic/reference/classic-layout.md，将每个逻辑根目录绑定到相应目录。如果协议已在上下文中，请勿重新加载。所有 OpenSpec CLI 调用都使用适配器，路径使用已绑定的 <classic-*> 根目录；不要先额外运行一次 root show。

SDK Run 路径

首次进入当前 SDK 阶段、移交给新的 Agent，或恢复上下文时，请阅读阶段进入与恢复及该参考文档中当前阶段对应的章节。如果本会话中已有且仍有效，请复用这些内容。继续执行下方阶段；基于 nextAction.kind 的恢复路由仅适用于没有续接模式的旧响应。

复用当前有效结果中的 agent.continuation / data.nextAction 和已绑定状态。仅在冷恢复、外部状态发生变化或缺少必要信息时，才运行 comet state next <change-name> --json。对于 data.runtimeFormat: sdk，仅推进此 Run；实现方法、计划内容和评审见 SDK 执行方法；通过本节提交状态和证据。data.phase 必须为 build。复用上下文中已有的有效布局和配置；仅在缺少时运行 comet state check <change-name> build --json。对于 nextAction.kind: reconcile，运行 comet state check <change-name> build --recover --json，并在重复外部工作之前确认原始结果。

首先检查有效配置中的 workflow 或当前 nextAction.stepId。对于 tweak.build.* / workflow: tweak，**立即执行：**使用 Skill 工具加载 comet-tweak skill。禁止跳过此步骤。对于 hotfix.build.* / workflow: hotfix，**立即执行：**使用 Skill 工具加载 comet-hotfix skill。禁止跳过此步骤。Skill 加载后，传入相同的 change、workspace、phase、Run revision 和 continuation，并恢复其 SDK Build 步骤。不要要求完整的 Design Doc 或实现计划，也不要重复 Open。旧版 Run 可能仍将 comet-build 存储为原始 Action 引用；按相同方式路由。升级获批后，若当前步骤为 full.build.*，请使用 SDK 执行方法中的完整路径。

1. 在 full.build.configure 阶段，检查 SDK 执行方法下已有的选择，只询问执行、TDD 和审查方面尚未确定的事项。将已确认的 build_mode、tdd_mode、review_mode、subagent_dispatch，以及需要时的 direct_override，写入仓库内的临时 JSON 文件。如果用户已明确选择完整配置，则运行 comet state propose-build <change-name> --file <configuration-json> --confirmed，同时保存提案和批准。否则运行 comet state propose-build <change-name> --file <configuration-json>。仅当仍有待处理的 Wait 时，才保存 data.wait.proposalHash，展示实际配置，并根据 decision-point.md 等待确认。然后运行 comet state decide-build <change-name> --proposal-hash <proposalHash> --choice <approved|rejected>。若遭到拒绝，则提出修订后的选项。恢复时，沿用已有的待处理 Wait。
2. 在 full.build.plan 阶段，根据 SDK 执行方法创建或检查计划。参考当前 Design Doc 和 tasks.md，使用 和 映射任务，而不要另建一份复选清单。运行 comet state submit-plan <change-name> --plan <plan-ref>。仅当用户明确要求规划后暂停时，才添加 --pause。对于 plan-ready Wait，等待用户明确指示继续，并在 comet state continue-plan <change-name> --proposal-hash <proposalHash> 中使用其当前哈希。计划或任务要求发生变化后，不得沿用先前的批准。
3. 在 full.build.execute 阶段，使用选定的方法实施、审查任务或分段，并运行相关检查。只有在实际完成且审查满意后，才在同一个 tasks.md 中勾选任务。使用共享的 state tasks、state task-complete 和 state checkpoint 工具处理任务 ID、完成状态和协作进度；这些工具不会推进 SDK Run。SDK 不得调用旧版 comet handoff --write。计划、任务和工作区一致后，运行 comet state complete-build <change-name> --session <builder-execution-ref> 进入检查 Action。提交前解决所有不一致。
4. 在 full.build.check 阶段，运行 comet guard <change-name> build --apply -- <program> [args...]，并为此工作区提供明确且完整的构建或验收命令。此处无需新的用户决策：--apply 会在执行检查并于同一 Run 中记录回执前，重新验证当前任务、配置、工作区和证据。只有有效且成功的证据才能进入 Verify。仅在需要诊断时，使用只读预览 comet guard <change-name> build。如果提交回执时中断，应先调查 Action 和检查记录，再重新执行任何操作。失败时，根据返回的当前 Build Action 修复原因；仅在未返回后续操作时，才读取 state next --json。

每次推进后，使用该结果中的 agent.continuation / data.nextAction。状态有效且完整时，不要重复调用 next、select 或 check；仅在冷启动恢复、外部状态发生变化或信息缺失时重新读取。仅当下一阶段的 action 需要时，才加载下一个 Skill；在当前 Run 中处理 decision、evidence 和 reconcile。 对于确定性的本地检查，按照 SDK execution methods 中的说明，在 -- 前添加 --local；Runtime 会在复用前验证完整输入和日志。外部检查仍会执行。使用稳定的 --session <builder-execution-ref> 将 SDK Build 关联起来；如果提供了该参数，完整的 complete-build 已会携带它。

兼容路径

其余原有 Runtime 步骤仅适用于 runtimeFormat: compat。阅读 兼容操作，并继续当前阶段。SDK 不会加载该参考文档。