@house365/comate 0.9.3 → 0.9.4

package/package.json

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

package/skills/comate/SKILL.md

@@ -1,217 +1,217 @@
----
-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
+---
+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