@house365/comate 0.9.0 → 0.9.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@house365/comate",
-  "version": "0.9.0",
-  "description": "comate —— Spec-First 规约驱动的 AI 开发编排器（Agent Skills）",
+  "version": "0.9.2",
+  "description": "comate —— SDD (规约驱动开发) 的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",
   "publishConfig": {

package/skills/comate/SKILL.md

@@ -1,217 +1,217 @@
----
-name: comate
-description: "comate —— Spec-First 规格驱动开发编排器。用 /comate 自动探测阶段并分派。五阶段：open → design → build → verify → archive。"
----
-
-# comate —— OpenSpec + Superpowers 规格驱动开发流
-
-
-**核心原则：brainstorming 不可跳过。每个变更都必须经过深度设计（fix 预设除外）。**
-
----
-
-## 决策核心
-
-agent 做决策只需读本节，其余参见末尾「参考附录」。决策阻塞点的完整规则见 `comate/reference/decision-points.md`（单一真相源）。
-
-### 自动阶段探测
-
-**Step 0：活跃 change 发现 + 意图探测**
-
-1. 先探测预设；命中 fix 条件则直接调用 `/comate-fix`，不进入普通 open 分支。
-2. 无预设命中时，运行 `openspec list --json` 获取所有活跃 change。
-
-**预设探测优先级最高**：
-- 用户明确描述 bug 修复或文案/配置/文档/prompt 小调整 + 满足 fix 条件 → 直接调用 `/comate-fix`
-- **用户输入指向一份原始 PRD**（给了 PRD 路径/编号，或明确说「这是 PRD / 从这份需求文档开始」，典型路径 `docs/knowledge-base/**/PRD-*.md`）**且无对应活跃 change** → 直接调用 `/comate-gate`（阶段 0：先过门禁，再拆分建 change）。不要直接调 `/comate-open`——PRD 必须先过质量门禁。
-- 无预设命中 → 按下表处理
-
-| 活跃 change | 用户输入 | 行为 |
-|-------------|----------|------|
-| 无 | 指向原始 PRD | → 调用 `/comate-gate` |
-| 无 | 非预设输入 | → 调用 `/comate-open` |
-| 恰好 1 个 | `/comate <描述>` | → **询问**：继续该 change 还是新建 |
-| 多个 | `/comate <描述>` | → **询问**：继续已有还是新建；继续则列出供选择 |
-| 恰好 1 个 | `/comate` 无描述 | → 自动选中，进入 Step 1 |
-| 多个 | `/comate` 无描述 | → 列出 change 供用户选择 |
-
-<IMPORTANT>
-用户选择「新建 change」时，**必须调用 `/comate-open`**，不要直接调 `/opsx:new`。
-`/comate-open` 做双重初始化：OpenSpec 产物（由内部 `/opsx:new` 创建）+ `.comate.yaml` 状态文件。
-直接调 `/opsx:new` 会导致 `.comate.yaml` 缺失，破坏后续阶段探测。
-</IMPORTANT>
-
-**Step 1：读取 `.comate.yaml` 状态元数据**
-
-优先读 `openspec/changes/<name>/.comate.yaml`。不可用时回落到 `openspec status --change "<name>" --json`、`tasks.md`、`docs/superpowers/` 文件检查。
-
-**断点恢复规则**：
-- 每次上下文恢复都重跑 Step 0、Step 1；不要信任对话历史做阶段探测。
-- 有活跃 change 且工作树有未提交改动时，按 `comate/reference/dirty-worktree.md` 协议处理。
-- 若 `phase: build`，先检查 `build_mode`、`isolation`、`tdd_mode` 是否已设；任一未设则回 `/comate-build` 对应步骤补充；都已设则读 tasks.md 下一个未勾选任务继续。
-- 若 `phase: verify` 且 `verify_result: fail`，按决策点 4 分级处理：CRITICAL 失败直接 `state transition <name> verify-fail` 回 `/comate-build`（不询问，回退前报告失败项）；仅 WARNING/SUGGESTION 或 Spec 漂移时才 AskUserQuestion 暂停。
-- 若 `phase: open` 但 proposal/design/tasks 已完成，先 `bash "$COMATE" guard <name> open --apply` 修复状态，再继续探测。
-- 若 `phase: archive`，只调用 `/comate-archive`；归档成功后 change 移入 archive 目录，不要再对旧活跃目录跑 guard。
-
-**Step 2：阶段判定**（按顺序检查，首个命中者生效）
-
-1. `archived: true` 或 change 已移入 archive → 流程完成
-2. `verify_result: pass` 且 `archived` 非 `true` → 调用 `/comate-archive`
-3. `verify_result: fail` → 验证失败决策阻塞点（决策点 4）
-4. `phase: verify` 或 tasks.md 全勾 → 调用 `/comate-verify`
-5. `phase: build` 或有 Design Doc 但 plan/执行未完成 → 按 workflow 路由：`fix`→`/comate-fix`，`full`→`/comate-build`
-6. `phase: design` 或有 change 但无 Design Doc → 调用 `/comate-design`
-7. `phase: open` 或有活跃 change 但 `.comate.yaml` 缺失 → 调用 `/comate-open`
-8. 无活跃 change → 调用 `/comate-open`
-
-元数据与文件状态冲突时，以可验证的文件状态为准，先用 `state set` 修正 `.comate.yaml` 再继续。
-
-### 预设升级判定
-
-**fix → full**：见 `/comate-fix` 的两种模式升级条件（bug 模式 3+ 文件 / 架构变更 / schema 变更 / 新 API / 跨模块；调整模式 5+ 文件 / 多模块协调 / 5+ 测试 / 配置项增删 / 新 capability / delta spec）。
-
-### 错误处理速查
-
-| 场景 | 处理 |
-|------|------|
-| `openspec list --json` 失败 | 检查 openspec 是否安装，提示运行 `comate init` |
-| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
-| `.comate.yaml` 损坏或缺失 | 以文件状态为真相源，用 `bash "$COMATE" state set` 修正后继续 |
-| 构建/测试失败 | 回 build 阶段修复，不进入 verify |
-| change 目录结构不全 | 按 `comate-open` 产物要求补齐缺失文件 |
-
-### 阶段流转
-
-<IMPORTANT>
-一次 `/comate` 调用从探测到的阶段开始，满足退出条件后推进到下一阶段。
-
-流转链：open → design → build → verify → archive
-
-**连续执行要求**：从探测到的阶段开始，agent 自动连续走完后续阶段。但**自动推进仅适用于无用户决策的流转点**。遇到决策阻塞点时，**必须用 AskUserQuestion 工具暂停等待用户明确回应**，不得用推荐规则、默认值或历史偏好替代用户确认，也不得只输出文字提示后继续执行。
-
-7 个决策点（部分含自动处理分支）+ Red Flags 表见 `comate/reference/decision-points.md`。**每个决策点先按三类行动分类**（用户决策 / 自动处理 / 停止条件）：判定属用户决策才用 AskUserQuestion 阻塞等待用户选择；属自动处理则直接执行并如实报告；其他无歧义流转自动进行，不得中途退出。
-</IMPORTANT>
-
----
-
-## 子命令速查
-
-| 命令 | 阶段 | Owner | 产物 |
-|------|------|-------|------|
-| `/comate-gate` | 0. PRD 门禁与拆分 | Claude | `<PRD>.gate.yaml`, 评审报告, N 个 change |
-| `/comate-open` | 1. 开题 | OpenSpec | proposal.md, design.md, tasks.md |
-| `/comate-design` | 2. 深度设计 | Superpowers | Design Doc, delta spec |
-| `/comate-build` | 3. 计划与构建 | Superpowers | 实施计划, 代码提交 |
-| `/comate-verify` | 4. 验证收尾 | 双方 | 验证报告, 分支处理 |
-| `/comate-archive` | 5. 归档 | OpenSpec | delta→main spec 同步, design doc 标注, 归档 |
-| `/comate-fix` | 预设 | 双方 | 快速小改动（bug 修复 + 非 bug 调整，跳过 brainstorming） |
-| `/comate-kb-integration` | 工具 | Claude | 第三方对接档案(从官方文档 URL 生成 integrations 目录档案) |
-
-```
-[原始 PRD] ──→ /comate-gate ──┐  (门禁+拆分，扇出 N 个 change)
-                  (Claude)        │
-/comate                           ▼
-  ↓ 自动探测
-/comate-open ──→ /comate-design ──→ /comate-build ──→ /comate-verify ──→ /comate-archive
-  (OpenSpec)      (Superpowers)      (Superpowers)      (双方)            (OpenSpec)
-```
-
-需求来自对话时从 `/comate-open` 起步；来自原始 PRD 时先过 `/comate-gate` 门禁再拆分。
-
----
-
-## 参考附录
-
-### 脚本定位（单一入口）
-
-comate 收敛为**一个分发器** `comate/scripts/comate.sh`。skill 里只需定位这一个脚本并缓存到 `$COMATE`：
-
-```bash
-COMATE="${COMATE:-$(for r in . ./.agents/skills ./.claude/skills ./.cursor/skills ./.codex/skills "$HOME"/.agents/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills "$HOME"/.codex/skills "$HOME"/.gemini/skills; do
-  [ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
-done | head -1)}"
-if [ -z "$COMATE" ]; then
-  echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
-  return 1 2>/dev/null || exit 1
-fi
-```
-
-之后全程复用 `$COMATE`：
-
-```bash
-bash "$COMATE" state   <name> init <full|fix>
-bash "$COMATE" state   <name> transition <event>
-bash "$COMATE" state   <name> check <phase> [--json]
-bash "$COMATE" state   <name> recover <phase>
-bash "$COMATE" state   <name> scale
-bash "$COMATE" state   <name> validate
-bash "$COMATE" guard   <name> <phase> [--apply] [--json]
-bash "$COMATE" handoff <name> <design|build> --write [--full]
-bash "$COMATE" sources <name> track <file...> [--note <text>]
-bash "$COMATE" sources <name> check | list
-bash "$COMATE" sources find <file>
-bash "$COMATE" archive <name> [--dry-run]
-bash "$COMATE" status
-bash "$COMATE" doctor
-```
-
-`guard --apply` 在检查全 PASS 后委托 `state transition` 自动流转。退出码契约：`0` 通过 / `1` 校验阻塞 / `2` 用法错误 / `3` 环境缺失 / `4` 状态文件损坏。
-
-### `.comate.yaml` 字段参考
-
-状态文件为「扁平 `key: value`」子集（不允许嵌套/列表/多行）。完整字段模板见 `comate/scripts/comate-lib.sh` 的 `FIELD_ORDER`。关键字段：
-
-| 字段 | 含义 |
-|------|------|
-| `schema_version` | 状态文件格式版本（当前 1） |
-| `workflow` | `full` / `fix` |
-| `phase` | `open` / `design` / `build` / `verify` / `archive` |
-| `build_mode` | `subagent-driven-development` / `executing-plans` / `direct` |
-| `tdd_mode` | `tdd` / `direct`（build→verify 前必须已选；fix 默认 `direct`） |
-| `isolation` | `branch` / `worktree`（build→verify 前必须已选） |
-| `verify_mode` | `light` / `full`（由 scale 评估写入） |
-| `verify_result` | `pending` / `pass` / `fail` |
-| `verification_report` | 验证报告路径，verify-pass 前必须指向真实文件 |
-| `branch_status` | `pending` / `handled` |
-| `handoff_context` / `handoff_hash` | design 交接包路径 + 源文件 sha256 |
-| `impl_context` / `impl_hash` | build 交接包路径 + plan+tasks 的 sha256（防漂移） |
-| `direct_override` | full 流程用 `direct` 需显式 `true` |
-| `base_ref` / `base_branch` | init 记录的 HEAD + 探测到的默认分支 |
-| `source_kind` / `source_manifest` | 需求来源类型（`conversation` / `file`）+ 知识库源文件清单路径（防漂移） |
-| `build_command` / `verify_command` | 可选，项目构建/验证命令 |
-
-状态机硬约束（由 `guard` 与 `state transition` 双重强制）：
-- `build → verify` 前 `isolation` 必须为 `branch` 或 `worktree`
-- `build → verify` 前 `build_mode` 必须已选
-- `build → verify` 前 `tdd_mode` 必须为 `tdd` 或 `direct`
-- `build_mode: direct` 默认仅 fix；full 流程需 `direct_override: true`
-- `verify → archive` 前 `verification_report` 指向真实文件、`branch_status: handled`、`impl_hash` 与当前 plan+tasks 一致
-
-### 文件结构
-
-```
-openspec/                              # OpenSpec —— WHAT
-├── changes/<name>/
-│   ├── .comate.yaml                   # comate 状态机真相源
-│   ├── proposal.md / design.md / tasks.md
-│   ├── specs/<capability>/spec.md     # delta 能力规格
-│   └── .comate/handoff/               # 脚本生成的阶段交接包
-│       └── ../sources.manifest        # 知识库源文件清单（source_kind=file 时）
-└── specs/<capability>/spec.md         # 主 spec（归档时由 delta 覆盖）
-
-docs/knowledge-base/<...>.md           # 可追踪的需求源文档（source_kind=file）
-
-docs/superpowers/                      # Superpowers —— HOW
-├── specs/YYYY-MM-DD-<topic>-design.md # Design Doc
-├── plans/YYYY-MM-DD-<feature>.md      # 实施计划
-└── reports/                           # 验证报告
-```
-
-### 最佳实践
-
-1. brainstorming 不可跳过（fix 除外）
-2. delta spec 是活文档，build 阶段随时改，归档时同步
-3. 交接包由脚本生成（`handoff`），guard 校验 source/hash/mode
-4. tasks.md 实时同步，每完成一个任务勾选并提交
-5. 验证通过才归档
-6. 预设有边界，命中升级条件及时转 full
+---
+name: comate
+description: "comate —— SDD (规约驱动开发) 编排器。用 /comate 自动探测阶段并分派。五阶段：open → design → build → verify → archive。"
+---
+
+# comate —— SDD (规约驱动开发) 编排器
+
+
+**核心原则：brainstorming 不可跳过。每个变更都必须经过深度设计（fix 预设除外）。**
+
+---
+
+## 决策核心
+
+agent 做决策只需读本节，其余参见末尾「参考附录」。决策阻塞点的完整规则见 `comate/reference/decision-points.md`（单一真相源）。
+
+### 自动阶段探测
+
+**Step 0：活跃 change 发现 + 意图探测**
+
+1. 先探测预设；命中 fix 条件则直接调用 `/comate-fix`，不进入普通 open 分支。
+2. 无预设命中时，运行 `openspec list --json` 获取所有活跃 change。
+
+**预设探测优先级最高**：
+- 用户明确描述 bug 修复或文案/配置/文档/prompt 小调整 + 满足 fix 条件 → 直接调用 `/comate-fix`
+- **用户输入指向一份原始 PRD**（给了 PRD 路径/编号，或明确说「这是 PRD / 从这份需求文档开始」，典型路径 `docs/knowledge-base/**/PRD-*.md`）**且无对应活跃 change** → 直接调用 `/comate-gate`（阶段 0：先过门禁，再拆分建 change）。不要直接调 `/comate-open`——PRD 必须先过质量门禁。
+- 无预设命中 → 按下表处理
+
+| 活跃 change | 用户输入 | 行为 |
+|-------------|----------|------|
+| 无 | 指向原始 PRD | → 调用 `/comate-gate` |
+| 无 | 非预设输入 | → 调用 `/comate-open` |
+| 恰好 1 个 | `/comate <描述>` | → **询问**：继续该 change 还是新建 |
+| 多个 | `/comate <描述>` | → **询问**：继续已有还是新建；继续则列出供选择 |
+| 恰好 1 个 | `/comate` 无描述 | → 自动选中，进入 Step 1 |
+| 多个 | `/comate` 无描述 | → 列出 change 供用户选择 |
+
+<IMPORTANT>
+用户选择「新建 change」时，**必须调用 `/comate-open`**，不要直接调 `/opsx:new`。
+`/comate-open` 做双重初始化：OpenSpec 产物（由内部 `/opsx:new` 创建）+ `.comate.yaml` 状态文件。
+直接调 `/opsx:new` 会导致 `.comate.yaml` 缺失，破坏后续阶段探测。
+</IMPORTANT>
+
+**Step 1：读取 `.comate.yaml` 状态元数据**
+
+优先读 `openspec/changes/<name>/.comate.yaml`。不可用时回落到 `openspec status --change "<name>" --json`、`tasks.md`、`docs/superpowers/` 文件检查。
+
+**断点恢复规则**：
+- 每次上下文恢复都重跑 Step 0、Step 1；不要信任对话历史做阶段探测。
+- 有活跃 change 且工作树有未提交改动时，按 `comate/reference/dirty-worktree.md` 协议处理。
+- 若 `phase: build`，先检查 `build_mode`、`isolation`、`tdd_mode` 是否已设；任一未设则回 `/comate-build` 对应步骤补充；都已设则读 tasks.md 下一个未勾选任务继续。
+- 若 `phase: verify` 且 `verify_result: fail`，按决策点 4 分级处理：CRITICAL 失败直接 `state transition <name> verify-fail` 回 `/comate-build`（不询问，回退前报告失败项）；仅 WARNING/SUGGESTION 或 Spec 漂移时才 AskUserQuestion 暂停。
+- 若 `phase: open` 但 proposal/design/tasks 已完成，先 `bash "$COMATE" guard <name> open --apply` 修复状态，再继续探测。
+- 若 `phase: archive`，只调用 `/comate-archive`；归档成功后 change 移入 archive 目录，不要再对旧活跃目录跑 guard。
+
+**Step 2：阶段判定**（按顺序检查，首个命中者生效）
+
+1. `archived: true` 或 change 已移入 archive → 流程完成
+2. `verify_result: pass` 且 `archived` 非 `true` → 调用 `/comate-archive`
+3. `verify_result: fail` → 验证失败决策阻塞点（决策点 4）
+4. `phase: verify` 或 tasks.md 全勾 → 调用 `/comate-verify`
+5. `phase: build` 或有 Design Doc 但 plan/执行未完成 → 按 workflow 路由：`fix`→`/comate-fix`，`full`→`/comate-build`
+6. `phase: design` 或有 change 但无 Design Doc → 调用 `/comate-design`
+7. `phase: open` 或有活跃 change 但 `.comate.yaml` 缺失 → 调用 `/comate-open`
+8. 无活跃 change → 调用 `/comate-open`
+
+元数据与文件状态冲突时，以可验证的文件状态为准，先用 `state set` 修正 `.comate.yaml` 再继续。
+
+### 预设升级判定
+
+**fix → full**：见 `/comate-fix` 的两种模式升级条件（bug 模式 3+ 文件 / 架构变更 / schema 变更 / 新 API / 跨模块；调整模式 5+ 文件 / 多模块协调 / 5+ 测试 / 配置项增删 / 新 capability / delta spec）。
+
+### 错误处理速查
+
+| 场景 | 处理 |
+|------|------|
+| `openspec list --json` 失败 | 检查 openspec 是否安装，提示运行 `comate init` |
+| 子 skill 不可用 | 停止流程，提示安装或启用对应 skill |
+| `.comate.yaml` 损坏或缺失 | 以文件状态为真相源，用 `bash "$COMATE" state set` 修正后继续 |
+| 构建/测试失败 | 回 build 阶段修复，不进入 verify |
+| change 目录结构不全 | 按 `comate-open` 产物要求补齐缺失文件 |
+
+### 阶段流转
+
+<IMPORTANT>
+一次 `/comate` 调用从探测到的阶段开始，满足退出条件后推进到下一阶段。
+
+流转链：open → design → build → verify → archive
+
+**连续执行要求**：从探测到的阶段开始，agent 自动连续走完后续阶段。但**自动推进仅适用于无用户决策的流转点**。遇到决策阻塞点时，**必须用 AskUserQuestion 工具暂停等待用户明确回应**，不得用推荐规则、默认值或历史偏好替代用户确认，也不得只输出文字提示后继续执行。
+
+7 个决策点（部分含自动处理分支）+ Red Flags 表见 `comate/reference/decision-points.md`。**每个决策点先按三类行动分类**（用户决策 / 自动处理 / 停止条件）：判定属用户决策才用 AskUserQuestion 阻塞等待用户选择；属自动处理则直接执行并如实报告；其他无歧义流转自动进行，不得中途退出。
+</IMPORTANT>
+
+---
+
+## 子命令速查
+
+| 命令 | 阶段 | Owner | 产物 |
+|------|------|-------|------|
+| `/comate-gate` | 0. PRD 门禁与拆分 | Claude | `<PRD>.gate.yaml`, 评审报告, N 个 change |
+| `/comate-open` | 1. 开题 | OpenSpec | proposal.md, design.md, tasks.md |
+| `/comate-design` | 2. 深度设计 | Superpowers | Design Doc, delta spec |
+| `/comate-build` | 3. 计划与构建 | Superpowers | 实施计划, 代码提交 |
+| `/comate-verify` | 4. 验证收尾 | 双方 | 验证报告, 分支处理 |
+| `/comate-archive` | 5. 归档 | OpenSpec | delta→main spec 同步, design doc 标注, 归档 |
+| `/comate-fix` | 预设 | 双方 | 快速小改动（bug 修复 + 非 bug 调整，跳过 brainstorming） |
+| `/comate-kb-integration` | 工具 | Claude | 第三方对接档案(从官方文档 URL 生成 integrations 目录档案) |
+
+```
+[原始 PRD] ──→ /comate-gate ──┐  (门禁+拆分，扇出 N 个 change)
+                  (Claude)        │
+/comate                           ▼
+  ↓ 自动探测
+/comate-open ──→ /comate-design ──→ /comate-build ──→ /comate-verify ──→ /comate-archive
+  (OpenSpec)      (Superpowers)      (Superpowers)      (双方)            (OpenSpec)
+```
+
+需求来自对话时从 `/comate-open` 起步；来自原始 PRD 时先过 `/comate-gate` 门禁再拆分。
+
+---
+
+## 参考附录
+
+### 脚本定位（单一入口）
+
+comate 收敛为**一个分发器** `comate/scripts/comate.sh`。skill 里只需定位这一个脚本并缓存到 `$COMATE`：
+
+```bash
+COMATE="${COMATE:-$(for r in . ./.agents/skills ./.claude/skills ./.cursor/skills ./.codex/skills "$HOME"/.agents/skills "$HOME"/.claude/skills "$HOME"/.config/skills "$HOME"/.cursor/skills "$HOME"/.codex/skills "$HOME"/.gemini/skills; do
+  [ -d "$r" ] && find "$r" -maxdepth 6 -path '*/comate/scripts/comate.sh' -type f -print -quit 2>/dev/null
+done | head -1)}"
+if [ -z "$COMATE" ]; then
+  echo "ERROR: comate.sh 未找到，请确认 comate skill 已安装。" >&2
+  return 1 2>/dev/null || exit 1
+fi
+```
+
+之后全程复用 `$COMATE`：
+
+```bash
+bash "$COMATE" state   <name> init <full|fix>
+bash "$COMATE" state   <name> transition <event>
+bash "$COMATE" state   <name> check <phase> [--json]
+bash "$COMATE" state   <name> recover <phase>
+bash "$COMATE" state   <name> scale
+bash "$COMATE" state   <name> validate
+bash "$COMATE" guard   <name> <phase> [--apply] [--json]
+bash "$COMATE" handoff <name> <design|build> --write [--full]
+bash "$COMATE" sources <name> track <file...> [--note <text>]
+bash "$COMATE" sources <name> check | list
+bash "$COMATE" sources find <file>
+bash "$COMATE" archive <name> [--dry-run]
+bash "$COMATE" status
+bash "$COMATE" doctor
+```
+
+`guard --apply` 在检查全 PASS 后委托 `state transition` 自动流转。退出码契约：`0` 通过 / `1` 校验阻塞 / `2` 用法错误 / `3` 环境缺失 / `4` 状态文件损坏。
+
+### `.comate.yaml` 字段参考
+
+状态文件为「扁平 `key: value`」子集（不允许嵌套/列表/多行）。完整字段模板见 `comate/scripts/comate-lib.sh` 的 `FIELD_ORDER`。关键字段：
+
+| 字段 | 含义 |
+|------|------|
+| `schema_version` | 状态文件格式版本（当前 1） |
+| `workflow` | `full` / `fix` |
+| `phase` | `open` / `design` / `build` / `verify` / `archive` |
+| `build_mode` | `subagent-driven-development` / `executing-plans` / `direct` |
+| `tdd_mode` | `tdd` / `direct`（build→verify 前必须已选；fix 默认 `direct`） |
+| `isolation` | `branch` / `worktree`（build→verify 前必须已选） |
+| `verify_mode` | `light` / `full`（由 scale 评估写入） |
+| `verify_result` | `pending` / `pass` / `fail` |
+| `verification_report` | 验证报告路径，verify-pass 前必须指向真实文件 |
+| `branch_status` | `pending` / `handled` |
+| `handoff_context` / `handoff_hash` | design 交接包路径 + 源文件 sha256 |
+| `impl_context` / `impl_hash` | build 交接包路径 + plan+tasks 的 sha256（防漂移） |
+| `direct_override` | full 流程用 `direct` 需显式 `true` |
+| `base_ref` / `base_branch` | init 记录的 HEAD + 探测到的默认分支 |
+| `source_kind` / `source_manifest` | 需求来源类型（`conversation` / `file`）+ 知识库源文件清单路径（防漂移） |
+| `build_command` / `verify_command` | 可选，项目构建/验证命令 |
+
+状态机硬约束（由 `guard` 与 `state transition` 双重强制）：
+- `build → verify` 前 `isolation` 必须为 `branch` 或 `worktree`
+- `build → verify` 前 `build_mode` 必须已选
+- `build → verify` 前 `tdd_mode` 必须为 `tdd` 或 `direct`
+- `build_mode: direct` 默认仅 fix；full 流程需 `direct_override: true`
+- `verify → archive` 前 `verification_report` 指向真实文件、`branch_status: handled`、`impl_hash` 与当前 plan+tasks 一致
+
+### 文件结构
+
+```
+openspec/                              # OpenSpec —— WHAT
+├── changes/<name>/
+│   ├── .comate.yaml                   # comate 状态机真相源
+│   ├── proposal.md / design.md / tasks.md
+│   ├── specs/<capability>/spec.md     # delta 能力规格
+│   └── .comate/handoff/               # 脚本生成的阶段交接包
+│       └── ../sources.manifest        # 知识库源文件清单（source_kind=file 时）
+└── specs/<capability>/spec.md         # 主 spec（归档时由 delta 覆盖）
+
+docs/knowledge-base/<...>.md           # 可追踪的需求源文档（source_kind=file）
+
+docs/superpowers/                      # Superpowers —— HOW
+├── specs/YYYY-MM-DD-<topic>-design.md # Design Doc
+├── plans/YYYY-MM-DD-<feature>.md      # 实施计划
+└── reports/                           # 验证报告
+```
+
+### 最佳实践
+
+1. brainstorming 不可跳过（fix 除外）
+2. delta spec 是活文档，build 阶段随时改，归档时同步
+3. 交接包由脚本生成（`handoff`），guard 校验 source/hash/mode
+4. tasks.md 实时同步，每完成一个任务勾选并提交
+5. 验证通过才归档
+6. 预设有边界，命中升级条件及时转 full

package/skills/comate/reference/decision-points.md

@@ -1,77 +1,77 @@
-# 决策阻塞点清单（decision-points）
-
-规范路径：`comate/reference/decision-points.md`（单一真相源）
-
-本文件集中定义 comate 全流程中**必须暂停等待用户**的决策点。各阶段 SKILL 用一行引用本文件的某一条，而不重复叙述规则，避免措辞漂移。
-
-## 先判定：这里真的需要用户输入吗？
-
-到达一个候选决策点时，**先分类，再决定是否阻塞**。不要把"需要做出选择"等同于"需要问用户"。
-
-| 类别 | 判据 | 处理 |
-|------|------|------|
-| **用户决策** | 存在 ≥2 个有效选项，且不同选项会改变范围、行为、可接受的风险或产生不可逆结果 | 阻塞，按下方通用规则用 AskUserQuestion 等待用户 |
-| **自动处理** | 在用户请求范围内只剩一个安全动作：修复客观失败、调和可验证的状态、重试幂等检查、或遵循已持久化的配置 | 直接执行并如实报告，**不制造确认点** |
-| **停止条件** | 缺依赖、状态损坏、路径逃逸、外部命令不可用，无有效下一步 | 报告阻塞与恢复条件，**不发明选项** |
-
-三条落地准则：
-
-1. **能合并的选择合并问**：相邻、可一次答完的选择放进同一次 AskUserQuestion，不拆成多次暂停。
-2. **不重复问已持久化且仍有效的选择**：配置文件或状态已记录且未失效时，直接沿用并说明。
-3. **先做能力预检再展示选项**：只呈现当前平台/仓库真正可执行的选项；某字段只剩一个有效值时，解释原因并直接应用，不为它单独制造一次暂停。
-
-## 通用规则
-
-经上一节判定确属**用户决策**后，该节点即为**阻塞点**：当前 `/comate` 调用必须停止，**使用 AskUserQuestion 工具等待用户选择**。只有在用户明确选择后，才能写入对应状态字段并继续执行，然后恢复自动推进。
-
-- 文字输出**不能**替代工具等待。必须通过 AskUserQuestion 显式获得用户选择。
-- 不得用推荐规则、默认值或历史偏好替代**用户决策类**节点的确认。
-- 推荐规则只能用于在问题里说明建议，不能代替用户拍板。
-- 其他无歧义的阶段流转、以及经判定属"自动处理"的节点，必须自动进行，不得中途退出，也不得为其伪造一次用户确认。
-
-## 七个决策点
-
-1. **开题产物审视确认**（open）
-   proposal/design/tasks 三件套完成且内容完整后，**先按来源分类，再决定是否阻塞**（对齐本文件首节三类框架）：
-   - **对话来源**（`source_kind: conversation`）——范围此前未经任何用户拍板，三件套是第一次成形，属"用户决策"。暂停请用户确认或要求调整。
-   - **PRD 扇出且范围一致**——本 change 来自一份**已过门禁的 PRD**（可验证信号全部成立：`source_kind: file`、追踪的源是 PRD、`gate <prd> check` 返回 PASS、change 名已记入该 PRD `spawned_changes`），**且** proposal 的范围/目标/非目标忠实承接 gate 映射里本 change 认领的功能项、无擅自扩缩。此时范围/映射/命名已在决策点 6 由用户拍板，三件套只是承接，不产生新的 ≥2 有效选项 —— 只剩"继续"一个安全动作，属"自动处理"。**不 AskUserQuestion**，完整性检查通过即自动流转，并如实报告：承接自哪份 PRD、认领哪些功能项、已核对范围与映射一致。
-   - **PRD 扇出但范围有偏差**——proposal 与 gate 映射不一致（擅自扩大/缩小范围、认领了未分配的功能项、漏掉已分配项）时，分歧重新出现，属"用户决策"。**必须 AskUserQuestion 暂停**，展示偏差点，请用户裁定按映射修正还是接受新范围。
-   引用：`comate-open` Step 5。
-
-2. **设计方案确认**（design / brainstorming）
-   brainstorming 产出技术方案后，暂停请用户确认采用的方案、关键取舍、测试策略、Spec Patch。确认前不得创建最终 Design Doc、写 `design_doc`、跑 design guard 或进入 build。
-   引用：`comate-design` Step 1c。
-
-3. **构建工作方式选择**（build）
-   开始执行前，先做能力预检，再**一次性**就工作区隔离方式（current / branch / worktree）、执行方式（subagent-driven-development / executing-plans）、TDD 模式（tdd / direct）做一个**联合决策**；选 branch 时分支名也在同一次问清，不得二次暂停。
-   预检后某维度只剩一个可执行选项时，属"自动处理"：说明原因并直接写入对应字段，不为它单独制造暂停。仍有 ≥2 个有效选项的维度才进入 AskUserQuestion。三个维度全部只剩单值时，全部自动写入，本决策点跳过。
-   引用：`comate-build` Step 3。
-
-4. **验证失败决策**（verify）
-   验证不通过时先按严重程度分类，**只有真正的用户决策才阻塞**：
-   - **CRITICAL（构建失败 / 测试失败 / 安全问题 / 核心验收场景失败）** —— 属"自动处理"，唯一安全动作就是修复。直接执行 `state transition <name> verify-fail` 回到 build，如实报告失败项，**不询问**。
-   - **Spec 漂移**（design doc 与 delta spec 矛盾）—— 属"用户决策"，必须 AskUserQuestion 暂停（见 Step 2b 三选项）。
-   - **仅 WARNING / SUGGESTION，无任何 CRITICAL** —— 属"用户决策"（可接受偏差是合法选择），一次性批量展示并提供「全部修复 / 逐项处理 / 接受偏差（记录原因）」。
-   引用：`comate-verify` Step 1b、Step 2b 的 Spec 漂移处理。
-
-5. **分支收尾方式选择**（verify / finishing-a-development-branch）
-   暂停请用户选择：本地合并 / 推送建 PR / 保持分支 / 丢弃工作。仅在用户选择且对应操作完成后，才写 `branch_status: handled`。
-   引用：`comate-verify` Step 3。
-
-6. **预设升级确认**（fix → full）
-   命中升级条件（见 `comate-fix` SKILL 的「升级条件」，bug 模式与调整模式各有阈值）时，暂停请用户确认升级为完整 `/comate`。不得直接进入 `/comate-design`，不得自动补 Design Doc。用户确认后先 `state set <name> workflow full` 再进入完整流程。
-   引用：`comate-fix`「升级条件」。
-
-7. **构建期范围扩张**（build）
-   实施中发现需要重新设计或拆分新 change 时暂停。判定基准：以 tasks.md 初始任务总数为准，新增任务超过总数一半（50% 阈值）即视为超范围，请用户决定是否拆分。中等规模（接口变更、新增组件）确认后加载 `superpowers:brainstorming` 更新设计；大规模（全新 capability）确认后用 `/comate-open` 拆独立 change。
-   引用：`comate-build` Step 4。
-
-## Red Flags — 出现这些念头就停下来检查
-
-| Agent 的念头 | 实际风险 |
-|--------------|----------|
-| “用户大概会同意这个方案吧” | 不能替用户决定 —— 用 AskUserQuestion |
-| “这是个小改动，不用确认” | 决策点没有大小豁免 —— 阻塞点必须等待 |
-| “上次用户选了 A，这次也 A” | 历史偏好不能替代当前确认 |
-| “我把计划讲了，用户没反对” | 没反对 ≠ 同意 —— 必须用工具拿到明确选择 |
-| “流程都走到这了，应该没问题” | 验证未通过 ≠ 已通过 —— 检查 verify_result |
+# 决策阻塞点清单（decision-points）
+
+规范路径：`comate/reference/decision-points.md`（单一真相源）
+
+本文件集中定义 comate 全流程中**必须暂停等待用户**的决策点。各阶段 SKILL 用一行引用本文件的某一条，而不重复叙述规则，避免措辞漂移。
+
+## 先判定：这里真的需要用户输入吗？
+
+到达一个候选决策点时，**先分类，再决定是否阻塞**。不要把"需要做出选择"等同于"需要问用户"。
+
+| 类别 | 判据 | 处理 |
+|------|------|------|
+| **用户决策** | 存在 ≥2 个有效选项，且不同选项会改变范围、行为、可接受的风险或产生不可逆结果 | 阻塞，按下方通用规则用 AskUserQuestion 等待用户 |
+| **自动处理** | 在用户请求范围内只剩一个安全动作：修复客观失败、调和可验证的状态、重试幂等检查、或遵循已持久化的配置 | 直接执行并如实报告，**不制造确认点** |
+| **停止条件** | 缺依赖、状态损坏、路径逃逸、外部命令不可用，无有效下一步 | 报告阻塞与恢复条件，**不发明选项** |
+
+三条落地准则：
+
+1. **能合并的选择合并问**：相邻、可一次答完的选择放进同一次 AskUserQuestion，不拆成多次暂停。
+2. **不重复问已持久化且仍有效的选择**：配置文件或状态已记录且未失效时，直接沿用并说明。
+3. **先做能力预检再展示选项**：只呈现当前平台/仓库真正可执行的选项；某字段只剩一个有效值时，解释原因并直接应用，不为它单独制造一次暂停。
+
+## 通用规则
+
+经上一节判定确属**用户决策**后，该节点即为**阻塞点**：当前 `/comate` 调用必须停止，**使用 AskUserQuestion 工具等待用户选择**。只有在用户明确选择后，才能写入对应状态字段并继续执行，然后恢复自动推进。
+
+- 文字输出**不能**替代工具等待。必须通过 AskUserQuestion 显式获得用户选择。
+- 不得用推荐规则、默认值或历史偏好替代**用户决策类**节点的确认。
+- 推荐规则只能用于在问题里说明建议，不能代替用户拍板。
+- 其他无歧义的阶段流转、以及经判定属"自动处理"的节点，必须自动进行，不得中途退出，也不得为其伪造一次用户确认。
+
+## 七个决策点
+
+1. **开题产物审视确认**（open）
+   proposal/design/tasks 三件套完成且内容完整后，**先按来源分类，再决定是否阻塞**（对齐本文件首节三类框架）：
+   - **对话来源**（`source_kind: conversation`）——范围此前未经任何用户拍板，三件套是第一次成形，属"用户决策"。暂停请用户确认或要求调整。
+   - **PRD 扇出且范围一致**——本 change 来自一份**已过门禁的 PRD**（可验证信号全部成立：`source_kind: file`、追踪的源是 PRD、`gate <prd> check` 返回 PASS、change 名已记入该 PRD `spawned_changes`），**且** proposal 的范围/目标/非目标忠实承接 gate 映射里本 change 认领的功能项、无擅自扩缩。此时范围/映射/命名已在决策点 6 由用户拍板，三件套只是承接，不产生新的 ≥2 有效选项 —— 只剩"继续"一个安全动作，属"自动处理"。**不 AskUserQuestion**，完整性检查通过即自动流转，并如实报告：承接自哪份 PRD、认领哪些功能项、已核对范围与映射一致。
+   - **PRD 扇出但范围有偏差**——proposal 与 gate 映射不一致（擅自扩大/缩小范围、认领了未分配的功能项、漏掉已分配项）时，分歧重新出现，属"用户决策"。**必须 AskUserQuestion 暂停**，展示偏差点，请用户裁定按映射修正还是接受新范围。
+   引用：`comate-open` Step 5。
+
+2. **设计方案确认**（design / brainstorming）
+   brainstorming 产出技术方案后，暂停请用户确认采用的方案、关键取舍、测试策略、Spec Patch。确认前不得创建最终 Design Doc、写 `design_doc`、跑 design guard 或进入 build。
+   引用：`comate-design` Step 1c。
+
+3. **构建工作方式选择**（build）
+   开始执行前，先做能力预检，再**一次性**就工作区隔离方式（current / branch / worktree）、执行方式（subagent-driven-development / executing-plans）、TDD 模式（tdd / direct）做一个**联合决策**；选 branch 时分支名也在同一次问清，不得二次暂停。
+   预检后某维度只剩一个可执行选项时，属"自动处理"：说明原因并直接写入对应字段，不为它单独制造暂停。仍有 ≥2 个有效选项的维度才进入 AskUserQuestion。三个维度全部只剩单值时，全部自动写入，本决策点跳过。
+   引用：`comate-build` Step 3。
+
+4. **验证失败决策**（verify）
+   验证不通过时先按严重程度分类，**只有真正的用户决策才阻塞**：
+   - **CRITICAL（构建失败 / 测试失败 / 安全问题 / 核心验收场景失败）** —— 属"自动处理"，唯一安全动作就是修复。直接执行 `state transition <name> verify-fail` 回到 build，如实报告失败项，**不询问**。
+   - **Spec 漂移**（design doc 与 delta spec 矛盾）—— 属"用户决策"，必须 AskUserQuestion 暂停（见 Step 2b 三选项）。
+   - **仅 WARNING / SUGGESTION，无任何 CRITICAL** —— 属"用户决策"（可接受偏差是合法选择），一次性批量展示并提供「全部修复 / 逐项处理 / 接受偏差（记录原因）」。
+   引用：`comate-verify` Step 1b、Step 2b 的 Spec 漂移处理。
+
+5. **分支收尾方式选择**（verify / finishing-a-development-branch）
+   暂停请用户选择：本地合并 / 推送建 PR / 保持分支 / 丢弃工作。仅在用户选择且对应操作完成后，才写 `branch_status: handled`。
+   引用：`comate-verify` Step 3。
+
+6. **预设升级确认**（fix → full）
+   命中升级条件（见 `comate-fix` SKILL 的「升级条件」，bug 模式与调整模式各有阈值）时，暂停请用户确认升级为完整 `/comate`。不得直接进入 `/comate-design`，不得自动补 Design Doc。用户确认后先 `state set <name> workflow full` 再进入完整流程。
+   引用：`comate-fix`「升级条件」。
+
+7. **构建期范围扩张**（build）
+   实施中发现需要重新设计或拆分新 change 时暂停。判定基准：以 tasks.md 初始任务总数为准，新增任务超过总数一半（50% 阈值）即视为超范围，请用户决定是否拆分。中等规模（接口变更、新增组件）确认后加载 `superpowers:brainstorming` 更新设计；大规模（全新 capability）确认后用 `/comate-open` 拆独立 change。
+   引用：`comate-build` Step 4。
+
+## Red Flags — 出现这些念头就停下来检查
+
+| Agent 的念头 | 实际风险 |
+|--------------|----------|
+| “用户大概会同意这个方案吧” | 不能替用户决定 —— 用 AskUserQuestion |
+| “这是个小改动，不用确认” | 决策点没有大小豁免 —— 阻塞点必须等待 |
+| “上次用户选了 A，这次也 A” | 历史偏好不能替代当前确认 |
+| “我把计划讲了，用户没反对” | 没反对 ≠ 同意 —— 必须用工具拿到明确选择 |
+| “流程都走到这了，应该没问题” | 验证未通过 ≠ 已通过 —— 检查 verify_result |