comet-tweak

Comet 预设：Tweak

开始或继续之前，请阅读并遵循 comet-classic/reference/classic-layout.md。所有 OpenSpec CLI 调用都必须使用适配器，所有路径都必须使用绑定的 <classic-*> 逻辑根目录。

Tweak 为 Comet 的五阶段工作流提供预设选项。它使用 OpenSpec 处理需求和实现，复用 open/build/verify/archive，并跳过 Superpowers 头脑风暴和完整的实现计划。它不会创建单独的工作流。

适用于配置、文档或提示词调整，以及需要规范驱动实现（包括增量规范），但不需要完整 /comet-classic 深度设计流程的中等规模变更。增量规范是 Tweak 的常规产物；仅仅需要增量规范本身并不是升级流程的理由。

以下适用条件必须全部满足：

1. 工作符合单个 OpenSpec 变更的范围。
2. 无需 Superpowers 设计文档和完整的实现计划即可明确解决方案。
3. 无需跨模块或跨层的架构协调。
4. 可以估算任务范围。文件数和任务数只是参考，不会自动触发升级；请参阅“升级决策”。

预设可能不再适用的情形： 如果实现过程中遇到“升级决策”中列出的变更，请让用户决定是否采用完整的 /comet-classic 流程。

首次进入某个阶段、移交给新的 Agent，或恢复上下文时，请阅读并遵循任务上下文与产物语言。优先使用当前续接内容或已认领 Action 的 contextRequest；在同一阶段的连续工作期间，不要反复检索。

个人记忆中只保存可复用的用户信息，绝不保存任务摘要、进度、命令输出或测试结果。

SDK 运行路径

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

进入或恢复时，重复使用当前有效结果中的 agent.continuation / data.nextAction，以及绑定的变更、工作区、阶段和 Run 修订版本。根据已知的 data.runtimeFormat 路由。只有在冷恢复、外部状态发生变化或缺少这些信息时，才运行 comet state next <change-name> --json。对于 sdk，请使用本节处理状态变更。SDK 执行方法中的适用性、OpenSpec 应用方法、升级和文件数授权规则均适用；请通过本节提交状态和证据。对于 nextAction.kind: reconcile，运行 comet state check <change-name> <phase> --recover --json 调查原始 Action；在结果未知时，不要重复实现、检查或归档。

1. 对于新的变更，请根据工作区选择选择隔离方式。运行 comet classic workspace prepare <name> --isolation <selected-isolation> --json，输入 projectRoot；先根据入口与制品创建 OpenSpec 基础目录，然后运行 comet state init <name> tweak --isolation <selected-isolation>；接着运行 comet state select <name> 绑定 Hook 路由。在 SDK 执行方法下创建 OpenSpec 制品，包括此变更所需的任何增量规范。预览 comet guard <change-name> open --json。保存 data.approvalHash，向用户展示 Open 制品和范围，并在运行 comet guard <change-name> open --apply --approval-hash <approvalHash> 前取得明确批准。如果制品发生变化，请重新预览并再次取得批准；不要重复使用旧哈希。只有当 Run 进入 Build 时，Open 才算完成。
2. 在 tweak.build.execute 阶段，保持同一变更、工作区和 Run，直接恢复 Build；不要再次初始化或重复 Open。遵循 SDK 文档方法中的 OpenSpec 应用方法，并完成同一份 tasks.md。如果出现实质性升级信号，或文件数量超出限制且没有有效授权，请运行 comet state propose-escalation <change-name> --reason "<reason>"。说明继续采用 tweak 与升级为 full 的原因和影响；保存 data.wait.proposalHash。在用户明确选择后，运行 comet state decide-escalation <change-name> --proposal-hash <proposalHash> --choice <continue|upgrade>。继续仍须满足 SDK 执行方法中的范围、风险和裁定条件。升级后，同一 Run 和工作区将进入 full Design；立即通过标准触发器加载 comet-design。恢复时复用待处理的 Wait。
3. 任务完成且 tweak 仍然适用时，运行 comet guard <change-name> build --apply -- <program> [args...]，并附上完整的构建或验收命令。此处无需用户作出新的决定：--apply 会在执行并记录实际检查前，重新验证当前任务、配置、工作区和证据。只有有效检查成功后才能进入 Verify。仅在需要诊断时使用只读预览 comet guard <change-name> build。失败时使用返回的当前状态；只有未返回后续操作时才读取 state next --json；不要重放未知的 Action。
4. Run 进入 Verify 时，立即执行： 使用 Skill 工具加载 comet-verify skill。禁止跳过此步骤。适用时，在完整验证中检查增量规范的一致性；不要调用旧版 state set verify_mode。Run 进入 Archive 时，立即执行： 使用 Skill 工具加载 comet-archive skill。禁止跳过此步骤。归档和交付仍需当前用户授权；只有当前成功结果显示 Run 已完成时，才能声称任务已完成；如果缺少完成状态，请读取 state next --json。

每次推进后，使用该结果的 agent.continuation / data.nextAction。状态有效且完整时，不要重复执行 next、select 或 check；仅在冷启动恢复、外部状态发生变化或缺少信息时重新读取。在当前 Run 中解决 decision、evidence 或 reconcile；只有在状态为 action 时才执行相应步骤。 对于确定性的本地检查，按照 SDK 执行方法所述，在 -- 前添加 --local；Runtime 会在复用前验证完整输入并记录日志。外部检查仍须执行。将 SDK Build 与稳定的 --session <builder-execution-ref> 关联；如果提供该参数，full complete-build 已包含此参数。

兼容路径

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