# 用户决策点协议

规范路径：`comet-classic/reference/decision-point.md`

本协议由所有包含用户决策点的 comet 子 skill 共享。凡标注为“阻塞点”或“用户决策点”的步骤，都必须按本协议处理。

## 先判断是否真的需要用户决策

区分用户决策点、自动处理与停止条件：

- **用户决策点**：有两种或更多合法做法，而选择会影响范围、行为、由谁承担风险或不可逆的结果，必须由用户决定。阶段明确要求的产物/设计批准也属于用户决策点，应提供批准、调整或暂缓等选项；不能因为技术上只有一个推荐方案就自动通过
- **自动处理**：只有一个安全且在当前请求范围内的下一步，例如修复原因明确的失败、根据证据补齐状态、重试幂等检查，或按已保存的配置继续；直接执行并报告，不额外要求确认
- **停止条件**：依赖缺失、状态损坏、路径越界或外部命令不可用，导致当前没有合法下一步；报告阻塞原因和恢复条件，不得伪造选项
- **手动衔接**：`NEXT: manual` 只是交还控制权，不是新的用户决策点；输出 `HINT` 后结束当前调用，不再询问“是否继续”

只有第一类需要等待用户作出决定。Open/Design 因为范围、方案或验收要求尚不明确而提问时，同样按下方格式呈现。需要用户提供事实、路径或其他缺失内容，且无法列出真实选项时，说明缺少什么并请求补充，不编造答案。

相关且可以同时回答的问题必须放在一起提出；已保存且仍有效的选择不得重复询问。不要仅为了预测后续工具或操作是否失败，就额外预检并排除选项。展示本工作流支持的全部选择；用户选择后执行相应动作，若失败则停止并报告原错误。若某配置字段只有一个符合工作流要求的值，说明原因后直接采用，不为它单独暂停；此规则不替代阶段明确要求的用户确认。

## 核心规则

暂停或停止只影响依赖该决定、或被当前问题阻塞的动作。同一已授权范围内，其他不依赖该决定的调查、证据整理和已允许工作可以继续。不得因此绕过阶段 Guard、提前实施尚未确认的范围，或替用户作出决定。

- 决策点是阻塞点。到达决策点时必须暂停，等待用户明确选择后才能继续
- 存在 `AskUserQuestion` 时，使用它展示单选/多选选项；否则在对话中提出明确选项并等待用户回复
- 若无法使用 `AskUserQuestion`，就记录本会话无法使用结构化提问；本会话后续决策点不得反复重试它，直接改用文本选项
- 不得用推荐规则、默认值、历史偏好或“用户应该会同意”的推断代替当前确认
- 用户明确选择前，不得写入对应状态字段、执行对应分支操作或自动继续下一阶段

## Classic 预设的文件数授权复用

hotfix 和 tweak 的文件数阈值只触发范围复核，不是实质升级信号。预设可以复用 `<classic-change-dir>/.comet/rulings.md` 中的 `Preset file-count authorization`，但只有 active、workflow 与当前 change 匹配，scope、验收和风险假设未变，且当前唯一触发条件是文件数超限时，才把它视为有效授权。记录必须包含 `status: active|invalidated`、`workflow`、`decision: continue-on-file-count-only`、授权范围、`allowed-file-categories`、`authorization-basis` 和 `reason`。

命中有效授权时，不重新提问，但先报告交付文件总数和分类、它们与确认范围的对应关系、ruling 记录，以及没有命中实质升级信号的依据。恢复任务也必须先读取同一 ruling，再按当前 scope 和 workflow 重新核对。交付文件只统计源码、测试、用户文档、配置和生成物，覆盖基线后提交、暂存、未暂存及未跟踪文件并去重；排除 change 目录中的 OpenSpec 产物、`.comet` 元数据和无关脏文件。有效授权只绕过“文件数超限且没有实质升级信号”的提问，不能绕过新增模块、公共 API、schema、capability、跨模块或架构风险的复核。

普通开始修复、Skill 调用、历史偏好或 Personal Memory 不能建立授权。用户撤销、切换 workflow、范围或验收变化、出现新实质升级信号，或文件落到授权类别之外时，将 ruling 标为 `invalidated`；rulings.md 缺失、不可读、含糊或已失效时，无有效授权，必须按现有暂停流程提问。升级到 full 时也将 ruling 标为 `invalidated`，之后不得继续复用该授权。

## `AskUserQuestion` 优先策略

使用结构化提问时：

- 单选决策点用 `AskUserQuestion` 的单选问题；多选决策点用多选问题
- 每个问题都要说明正在决定什么；每个选项都要有简短名称和影响说明。有依据时标出推荐项并说明理由，但不能替用户选择
- 若工具调用成功，等待用户通过该问题作答；不得同时再输出一套文本选项
- 若工具不存在或调用失败，记录“本会话结构化提问不可用”，然后改用文本选项

## 每个问题必须包含的信息

- **问题**：说明本题要决定什么，并提供作出判断所需的事实、约束，或待确认产物的引用；不能只列工具名或配置字段
- **推荐与理由**：有依据时给出推荐选项，说明它为什么适合当前需求、风险与已有配置；依据不足时明确说明暂不推荐，不以历史偏好代替确认
- **选项与影响**：给出清晰可选项，逐项说明选择后执行什么、改变什么范围/行为、承担什么代价或风险；需要用户单选时，选项必须互斥且可执行
- 改用文本提问时，必须标明“单选”或“多选”，列出选项编号和各项影响，并要求用户回复编号；随后暂停依赖该回答的步骤，等待回复
- 一次提出多个问题时，每个问题分别满足问题、推荐理由与各选项影响要求；不能只为整组问题写一条笼统推荐
- 推荐只能供用户参考，不能替代确认。工具返回空答案、用户未回复，或答复没有明确选择时，待定决定保持未确认
- 用户选择后，再执行对应命令或状态更新

### 批量文本提问格式

一次用文本提出多个问题时，保留 `Q1`、`Q2` 编号；每题分别写加粗标题、说明、选项和推荐回答。用 💬 标记问题、💡 标记推荐回答，题目之间用分隔线区分。每题按以下格式书写，并在同一条消息中完整发出：

```markdown
💬 **Q1｜<问题标题>（单选）**

<说明背景，以及选择会改变什么；复杂问题可以分段。>

| 选项 | 方案         | 实际影响                   |
| ---- | ------------ | -------------------------- |
| A    | <方案短名称> | <选择后改变什么及相关代价> |
| B    | <方案短名称> | <选择后改变什么及相关代价> |

💡 **推荐回答：A（<方案短名称>）**

推荐理由：<为什么适合当前需求与约束。>

---
```

题号保持稳定，追问沿用原题号；多选题标为“多选”。开放题标为“开放回答”，省略选项表，有可靠建议时给出“推荐回答”和理由；事实不足时明确写出“需要你补充”，只提供回答所需的背景或格式，不编造推荐内容。已有固定选项表时，保留原编号和完整影响说明，放在对应题目下，不为突出推荐而重新编号或删减选项。

全部问题之后统一说明答复方式，例如 `Q1：A；Q2：A+C；Q3：补充内容`，也允许用户按题号给出自己的答案；示例不代表默认选择。结构化工具可用时仍优先使用工具，把相同信息填入标题、说明和选项字段；不要求工具显示 Markdown 表格，调用成功后不再重复发送文本问题。

## 各阶段需要确认什么

当前阶段确实需要以下决定时，才读取对应阶段的详细规则；已保存且仍有效的授权或配置不重新确认。

- 入口/Open：目标 change 不明、是否拆分 PRD、如何隔离工作区仍需要选择时，把相关问题一起提出。Open 结束时一次确认名称、范围与产物；请求已经清晰时，不先单独要求批准摘要或命名。
- Design：brainstorming 形成可供检查的方案后，请用户确认正式设计。已有有效确认时，只补充尚未完成的产物和状态。
- Build：写计划前，仅在执行/TDD/review 配置缺失或用户要求更改时，一次确认相关配置；计划完成后默认继续。plan-ready 表示用户主动要求暂停，收到继续指令后沿用有效计划与配置，不重新发起配置决策。
- Verify：范围内原因明确且可以修复的失败，自动修复并重新验证。需要接受 WARNING/SUGGESTION 偏差、决定如何处理实现与 Spec 的不一致，或达到 Runtime 自动修复上限时，才询问用户。CRITICAL/IMPORTANT 问题必须解决。
- Archive：一次确认归档与 local/push/pr 交付方式。已有有效 delivery 授权且目标未变时，只完成剩余操作；实际结果不确定时，先只读核对。
- 范围改变：新增能力、公开行为或接口发生变化、验收要求或风险承担方式改变，以及出现预设规定的升级条件时，由对应阶段展示继续、调整或拆分等合法选择。任务拆细或数量增加本身，不代表范围扩大。