@house365/comate 0.10.0 → 0.10.2

package/skills/comate-design/SKILL.md

@@ -1,113 +1,113 @@
----
-name: comate-design
-description: "comate 阶段 2：深度设计。用 /comate-design 调用。通过 brainstorming 产出 Design Doc 和 delta spec。"
----
-
-# comate 阶段 2：深度设计（Design）
-
-## 前置条件
-
-- 活跃 change 已存在（proposal.md、design.md、tasks.md）
-- 无 Design Doc
-
-## 步骤
-
-### 0. 入口状态验证
-
-```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
-bash "$COMATE" state <name> check design
-```
-
-**幂等性检查**：
-
-1. 读取 `.comate.yaml` 的 `design_doc`、`handoff_context`、`handoff_hash`、`phase_step`
-
-2. **已完成 Step 1c（方案已确认）** 的判定条件（按优先级，首个命中即算）：
-   
+---
+name: comate-design
+description: "comate 阶段 2：深度设计。用 /comate-design 调用。通过 brainstorming 产出 Design Doc 和 delta spec。"
+---
+
+# comate 阶段 2：深度设计（Design）
+
+## 前置条件
+
+- 活跃 change 已存在（proposal.md、design.md、tasks.md）
+- 无 Design Doc
+
+## 步骤
+
+### 0. 入口状态验证
+
+```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
+bash "$COMATE" state <name> check design
+```
+
+**幂等性检查**：
+
+1. 读取 `.comate.yaml` 的 `design_doc`、`handoff_context`、`handoff_hash`、`phase_step`
+
+2. **已完成 Step 1c（方案已确认）** 的判定条件（按优先级，首个命中即算）：
+   
    a. **phase_step 明确标记已确认**（最高优先级）：
       - `phase_step` 值为 `design.approval-confirmed` 或 `design.complete`（旧版 `1c-confirmed` / `2` 兼容一次）
-      - → **立即判定为已完成 Step 1c**，跳过 Step 1a-1c
-   
-   b. **Design Doc 文件存在且格式正确**（次优先级）：
-      - `design_doc` 已设置且文件存在
-      - frontmatter 含 `comate_change: <name>`
-      - frontmatter 含 `role: technical-design`
-      - frontmatter 含 `canonical_spec: openspec`
-      - 文件内容非空（除了 frontmatter 外有实质设计内容）
-      - → **判定为已完成 Step 1c**，跳过 Step 1a-1c
-   
-   **说明**：之所以 `phase_step` 优先级更高，是因为它是原子操作记录的决策状态，即使 Design Doc 文件创建失败或被误删，也能防止重复进入决策流程。
-
-3. **幂等分支**：
+      - → **立即判定为已完成 Step 1c**，跳过 Step 1a-1c
+   
+   b. **Design Doc 文件存在且格式正确**（次优先级）：
+      - `design_doc` 已设置且文件存在
+      - frontmatter 含 `comate_change: <name>`
+      - frontmatter 含 `role: technical-design`
+      - frontmatter 含 `canonical_spec: openspec`
+      - 文件内容非空（除了 frontmatter 外有实质设计内容）
+      - → **判定为已完成 Step 1c**，跳过 Step 1a-1c
+   
+   **说明**：之所以 `phase_step` 优先级更高，是因为它是原子操作记录的决策状态，即使 Design Doc 文件创建失败或被误删，也能防止重复进入决策流程。
+
+3. **幂等分支**：
    - **已完成 Step 1c 且 Design Doc 存在** → 跳过 Step 1a-1c，检查交接包：
-     - 若 `handoff_context` 和 `handoff_hash` 已设置且验证通过 → 直接进入 Step 2 的 guard 检查
-     - 若交接包缺失或 hash 不匹配 → 重新生成交接包（`bash "$COMATE" handoff <name> design --write`），**但不重新 brainstorming，不重新确认方案**，然后进入 Step 2
+     - 若 `handoff_context` 和 `handoff_hash` 已设置且验证通过 → 直接进入 Step 2 的 guard 检查
+     - 若交接包缺失或 hash 不匹配 → 重新生成交接包（`bash "$COMATE" handoff <name> design --write`），**但不重新 brainstorming，不重新确认方案**，然后进入 Step 2
    - **已确认但 Design Doc 缺失** → 从 `.comate/design-candidate.md` 恢复已确认方案并创建 Design Doc；候选文件也缺失时停止并报告状态损坏，不得假称 Design Doc 已存在，也不得重新向用户询问同一决策
    - **未完成 Step 1c** → 继续 Step 1a
-
-4. **断点恢复**（根据 `phase_step` 值）：
+
+4. **断点恢复**（根据 `phase_step` 值）：
    - `phase_step` 为 `design.handoff-written`（或旧版 `1a`）→ 从 Step 1b 开始并改写新格式
    - `phase_step` 为 `design.brainstorm-complete` / `design.approval-awaiting`（或旧版 `1b`）→ 从候选文件恢复 Step 1c 并改写新格式
    - `phase_step` 为 `design.approval-confirmed` 或 `design.complete` → 见第 3 点幂等分支
-
+
 5. **特别注意**：即使上下文压缩或会话中断，只要 `phase_step` 已标记 `design.approval-confirmed` 或 Design Doc 文件存在且格式正确，**就不得重新执行 brainstorming 或重新要求用户确认方案**。
-
-### 1a. 生成 OpenSpec → Superpowers 交接包
-
-**必须由脚本生成，不允许 agent 临场手写 summary 代替。**
-
-```bash
-bash "$COMATE" handoff <name> design --write
-# 记录步骤完成
+
+### 1a. 生成 OpenSpec → Superpowers 交接包
+
+**必须由脚本生成，不允许 agent 临场手写 summary 代替。**
+
+```bash
+bash "$COMATE" handoff <name> design --write
+# 记录步骤完成
 bash "$COMATE" state <name> set phase_step design.handoff-written
-```
-
-脚本生成 `openspec/changes/<name>/.comate/handoff/design-context.{json,md}` 并在 `.comate.yaml` 写入 `handoff_context` / `handoff_hash`。默认是 **compact 可追溯摘录**（含脚本标记 `Generated-by: comate`、source path、line range、sha256），不是 agent summary。需全文时加 `--full`。
-
-交接包来源：`proposal.md`、`design.md`、`tasks.md`、`specs/*/spec.md`。
-
-### 1b. 执行 Brainstorming（带上下文）
-
-**立即执行：** 使用 Skill 工具加载 `superpowers:brainstorming`，ARGUMENTS 包含：
-
-```
-Change: <name>
-OpenSpec Context Pack: openspec/changes/<name>/.comate/handoff/design-context.md
-Machine handoff: openspec/changes/<name>/.comate/handoff/design-context.json
-
-OpenSpec 产物是上游事实源，不要重新定义需求，不要重写 proposal/spec。
-基于交接包做深度技术设计：实现方案、技术风险、测试策略、边界条件。
-如发现 delta spec 缺少验收场景，只能提出 Spec Patch 回写 OpenSpec delta spec；不要在 Design Doc 中创建第二份需求 spec。
-
-Design Doc frontmatter 必须最小化，只含：
----
-comate_change: <name>
-role: technical-design
-canonical_spec: openspec
----
-```
-
-禁止跳过；该技能不可用时停止流程并提示安装 Superpowers，不要用普通对话替代。
-
+```
+
+脚本生成 `openspec/changes/<name>/.comate/handoff/design-context.{json,md}` 并在 `.comate.yaml` 写入 `handoff_context` / `handoff_hash`。默认是 **compact 可追溯摘录**（含脚本标记 `Generated-by: comate`、source path、line range、sha256），不是 agent summary。需全文时加 `--full`。
+
+交接包来源：`proposal.md`、`design.md`、`tasks.md`、`specs/*/spec.md`。
+
+### 1b. 执行 Brainstorming（带上下文）
+
+**立即执行：** 使用 Skill 工具加载 `superpowers:brainstorming`，ARGUMENTS 包含：
+
+```
+Change: <name>
+OpenSpec Context Pack: openspec/changes/<name>/.comate/handoff/design-context.md
+Machine handoff: openspec/changes/<name>/.comate/handoff/design-context.json
+
+OpenSpec 产物是上游事实源，不要重新定义需求，不要重写 proposal/spec。
+基于交接包做深度技术设计：实现方案、技术风险、测试策略、边界条件。
+如发现 delta spec 缺少验收场景，只能提出 Spec Patch 回写 OpenSpec delta spec；不要在 Design Doc 中创建第二份需求 spec。
+
+Design Doc frontmatter 必须最小化，只含：
+---
+comate_change: <name>
+role: technical-design
+canonical_spec: openspec
+---
+```
+
+禁止跳过；该技能不可用时停止流程并提示安装 Superpowers，不要用普通对话替代。
+
 brainstorming 阶段不写最终 Design Doc；但必须把完整候选方案写入 `openspec/changes/<name>/.comate/design-candidate.md`，供确认与上下文恢复使用。
-
-**步骤完成后记录**：
-
-```bash
+
+**步骤完成后记录**：
+
+```bash
 bash "$COMATE" state <name> set phase_step design.brainstorm-complete
-```
-
-### 1c. 用户确认设计方案（决策阻塞点 2）
-
-**必须使用 AskUserQuestion 工具暂停等待用户明确确认设计方案**。规则见 `comate/reference/decision-points.md` 第 2 条。确认前不得创建最终 Design Doc、写 `design_doc`、跑 design guard 或进入 build。
-
+```
+
+### 1c. 用户确认设计方案（决策阻塞点 2）
+
+**必须使用 AskUserQuestion 工具暂停等待用户明确确认设计方案**。规则见 `comate/reference/decision-points.md` 第 2 条。确认前不得创建最终 Design Doc、写 `design_doc`、跑 design guard 或进入 build。
+
 展示摘要：采用的技术方案、关键取舍与风险、测试策略、Spec Patch（如有）。用户确认后才继续 Step 2；要求调整则继续迭代。
 
 提问前先确认候选文件非空，并持久化等待状态：
@@ -115,64 +115,64 @@ bash "$COMATE" state <name> set phase_step design.brainstorm-complete
 ```bash
 bash "$COMATE" state <name> set phase_step design.approval-awaiting
 ```
-
-**确认后的处理顺序（不可颠倒）**：
-
-1. **立即记录决策状态**：
-   ```bash
+
+**确认后的处理顺序（不可颠倒）**：
+
+1. **立即记录决策状态**：
+   ```bash
    bash "$COMATE" state <name> set phase_step design.approval-confirmed
-   ```
-
-2. **然后创建 Design Doc 文件**（保存到 `docs/superpowers/specs/YYYY-MM-DD-topic-design.md`），frontmatter 必须包含：
-   ```yaml
-   ---
-   comate_change: <name>
-   role: technical-design
-   canonical_spec: openspec
-   ---
-   ```
-
-3. **记录 design_doc 路径**：
-   ```bash
-   bash "$COMATE" state <name> set design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
-   ```
-
+   ```
+
+2. **然后创建 Design Doc 文件**（保存到 `docs/superpowers/specs/YYYY-MM-DD-topic-design.md`），frontmatter 必须包含：
+   ```yaml
+   ---
+   comate_change: <name>
+   role: technical-design
+   canonical_spec: openspec
+   ---
+   ```
+
+3. **记录 design_doc 路径**：
+   ```bash
+   bash "$COMATE" state <name> set design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+   ```
+
 **说明**：候选方案先落盘，确认后再记录 `design.approval-confirmed` 并创建最终文件。这样中断恢复既不会重复提问，也不会丢失创建 Design Doc 所需内容。
-
-### 2. 更新 comate 状态
-
-```bash
-# 记录 design_doc 路径
-bash "$COMATE" state <name> set design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
-
-# 如有 delta spec 变更，重新生成 handoff 以更新 hash
-bash "$COMATE" handoff <name> design --write
-
-# 记录步骤完成
+
+### 2. 更新 comate 状态
+
+```bash
+# 记录 design_doc 路径
+bash "$COMATE" state <name> set design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+
+# 如有 delta spec 变更，重新生成 handoff 以更新 hash
+bash "$COMATE" handoff <name> design --write
+
+# 记录步骤完成
 bash "$COMATE" state <name> set phase_step design.complete
-
-# 自动流转
-bash "$COMATE" guard <name> design --apply
-```
-
-无 delta spec 变更则跳过 handoff 重新生成。
-
-## 退出条件
-
-- Design Doc 已创建，frontmatter 含 `comate_change`、`role: technical-design`、`canonical_spec: openspec`
-- `handoff_context` / `handoff_hash` 已写入且 hash 与当前产物一致（guard 强制）
-- `design-context.md` 由脚本生成且含可追溯标记（guard 强制）
-- `design_doc` 已写入 `.comate.yaml`
-- **阶段守卫**：`bash "$COMATE" guard <name> design --apply` 全 PASS 后自动流转到 `phase: build`
-
-## 上下文压缩恢复
-
-```bash
-bash "$COMATE" state <name> recover design
-```
-
-脚本输出结构化恢复上下文，按 Recovery action 判断下一步。
-
-## 自动流转
-
-> **REQUIRED NEXT SKILL：** 调用 `comate-build` skill 进入计划与构建。
+
+# 自动流转
+bash "$COMATE" guard <name> design --apply
+```
+
+无 delta spec 变更则跳过 handoff 重新生成。
+
+## 退出条件
+
+- Design Doc 已创建，frontmatter 含 `comate_change`、`role: technical-design`、`canonical_spec: openspec`
+- `handoff_context` / `handoff_hash` 已写入且 hash 与当前产物一致（guard 强制）
+- `design-context.md` 由脚本生成且含可追溯标记（guard 强制）
+- `design_doc` 已写入 `.comate.yaml`
+- **阶段守卫**：`bash "$COMATE" guard <name> design --apply` 全 PASS 后自动流转到 `phase: build`
+
+## 上下文压缩恢复
+
+```bash
+bash "$COMATE" state <name> recover design
+```
+
+脚本输出结构化恢复上下文，按 Recovery action 判断下一步。
+
+## 自动流转
+
+> **REQUIRED NEXT SKILL：** 调用 `comate-build` skill 进入计划与构建。

package/skills/comate-gate/scaffold/docs/README.md

@@ -1,36 +1,36 @@
-# docs 文档目录说明
-
-本目录承载项目的长期文档,与代码同仓库、同评审、同版本管理。按用途分为以下几类:
-
-| 子目录 | 定位 | 说明 |
-|--------|------|------|
-| `architecture/` | 架构规范 | 前后端分层、依赖规则、命名、错误码等工程铁律,以仓库**当前实现**为准 |
-| `knowledge-base/` | 知识库 | 上游需求(PRD)与横向(第三方对接)的长期文档,详见其内 `README.md` |
-
-## architecture/
-
-工程约束的唯一来源,是 `/comate-gate` PRD 门禁审阅中「契约对齐」的事实源。改对应层代码前必须先读。
-
-**占位目录,需根据项目实际情况建立规范文档**。常见架构文档包含:
-
-- 后端分层 / 依赖 / DTO / 错误码 / 命名。
-- 前端分层 / API / store / 路由 / 命名。
-- 工程原则与铁律。
-
-> 这些是**架构规则文档,不是 capability spec**,不放在 `openspec/specs/` 下,也不参与 `openspec validate --strict`。
-> 调整架构相关代码时,必须同步更新对应文档。
-
-## knowledge-base/
-
-需求与第三方对接的长期文档,是 comate 变更流程的上游:
-
-- `requirements/` —— 原始 PRD(产品需求文档)。PRD 经 `/comate-gate` 门禁与拆分后,扇出为 N 个 comate change。
-- `integrations/` —— 第三方业务/接口对接档案与索引,跨多个变更长期维护。
-
-完整的命名规则、溯源约定与铁律见 `knowledge-base/README.md`。
-
-## 与 openspec/ 的边界
-
-- `docs/` 放**长期文档**(架构规范、需求、对接档案)。
-- `openspec/` 放**变更驱动的规格**:`changes/`(一次性变更)与 `specs/`(能力沉淀)。
-- 两者通过 PRD 门禁状态(`<PRD>.gate.yaml`)与 change 的 `sources.manifest` 打通。
+# docs 文档目录说明
+
+本目录承载项目的长期文档,与代码同仓库、同评审、同版本管理。按用途分为以下几类:
+
+| 子目录 | 定位 | 说明 |
+|--------|------|------|
+| `architecture/` | 架构规范 | 前后端分层、依赖规则、命名、错误码等工程铁律,以仓库**当前实现**为准 |
+| `knowledge-base/` | 知识库 | 上游需求(PRD)与横向(第三方对接)的长期文档,详见其内 `README.md` |
+
+## architecture/
+
+工程约束的唯一来源,是 `/comate-gate` PRD 门禁审阅中「契约对齐」的事实源。改对应层代码前必须先读。
+
+**占位目录,需根据项目实际情况建立规范文档**。常见架构文档包含:
+
+- 后端分层 / 依赖 / DTO / 错误码 / 命名。
+- 前端分层 / API / store / 路由 / 命名。
+- 工程原则与铁律。
+
+> 这些是**架构规则文档,不是 capability spec**,不放在 `openspec/specs/` 下,也不参与 `openspec validate --strict`。
+> 调整架构相关代码时,必须同步更新对应文档。
+
+## knowledge-base/
+
+需求与第三方对接的长期文档,是 comate 变更流程的上游:
+
+- `requirements/` —— 原始 PRD(产品需求文档)。PRD 经 `/comate-gate` 门禁与拆分后,扇出为 N 个 comate change。
+- `integrations/` —— 第三方业务/接口对接档案与索引,跨多个变更长期维护。
+
+完整的命名规则、溯源约定与铁律见 `knowledge-base/README.md`。
+
+## 与 openspec/ 的边界
+
+- `docs/` 放**长期文档**(架构规范、需求、对接档案)。
+- `openspec/` 放**变更驱动的规格**:`changes/`(一次性变更)与 `specs/`(能力沉淀)。
+- 两者通过 PRD 门禁状态(`<PRD>.gate.yaml`)与 change 的 `sources.manifest` 打通。

package/skills/comate-gate/scaffold/docs/architecture/README.md

@@ -1,31 +1,31 @@
-# architecture (架构规范占位目录)
-
-> ⚠️ **本目录由 `comate init` 创建为占位,内容需根据项目实际情况建立。**
-
-本目录是工程约束的**唯一来源**,也是 `/comate-gate` PRD 门禁审阅中「契约对齐架构文档」的事实源。
-
-## 为什么需要架构文档
-
-PRD 门禁审阅时,会检查数据来源、接口契约、命名规范、错误码、边界处理等是否明确。这些约束的**唯一事实源**应该是架构文档,而不是散落在 PRD/代码里的重复规则。
-
-`/comate-gate` 要求 PRD 里的契约「对齐并点名遵循了架构文档的哪条」,不硬编码具体值、不自造规则。
-
-## 建议包含的架构文档
-
-根据项目技术栈,常见架构文档包括:
-
-- **后端架构** — 分层(如 Controller / Service / Repository)、依赖规则、DTO 规范、错误码体系、命名约定、数据库表与字段命名、缓存 key 规范、权限收口。
-- **前端架构** — 分层(如 views / components / api)、状态管理、路由、API 调用规范、组件命名。
-- **工程原则** — 日志、监控、测试、发布流程等通用铁律。
-
-## 如何使用
-
-1. 根据项目实际情况,在本目录建立 `backend-architecture.md` / `frontend-architecture.md` 等文档。
-2. PRD 里涉及接口、数据库、错误码、命名时,引用并对齐这些文档的既有约定。
-3. 架构变更时,先更新本目录文档,再改代码。
-
-## 注意事项
-
-- 这些是**架构规则文档,不是 capability spec**,不放在 `openspec/specs/` 下。
-- 不参与 `openspec validate --strict`。
-- 由 `docs/knowledge-base/` 里的 PRD 引用,由 comate change 的 proposal/design 对齐。
+# architecture (架构规范占位目录)
+
+> ⚠️ **本目录由 `comate init` 创建为占位,内容需根据项目实际情况建立。**
+
+本目录是工程约束的**唯一来源**,也是 `/comate-gate` PRD 门禁审阅中「契约对齐架构文档」的事实源。
+
+## 为什么需要架构文档
+
+PRD 门禁审阅时,会检查数据来源、接口契约、命名规范、错误码、边界处理等是否明确。这些约束的**唯一事实源**应该是架构文档,而不是散落在 PRD/代码里的重复规则。
+
+`/comate-gate` 要求 PRD 里的契约「对齐并点名遵循了架构文档的哪条」,不硬编码具体值、不自造规则。
+
+## 建议包含的架构文档
+
+根据项目技术栈,常见架构文档包括:
+
+- **后端架构** — 分层(如 Controller / Service / Repository)、依赖规则、DTO 规范、错误码体系、命名约定、数据库表与字段命名、缓存 key 规范、权限收口。
+- **前端架构** — 分层(如 views / components / api)、状态管理、路由、API 调用规范、组件命名。
+- **工程原则** — 日志、监控、测试、发布流程等通用铁律。
+
+## 如何使用
+
+1. 根据项目实际情况,在本目录建立 `backend-architecture.md` / `frontend-architecture.md` 等文档。
+2. PRD 里涉及接口、数据库、错误码、命名时,引用并对齐这些文档的既有约定。
+3. 架构变更时,先更新本目录文档,再改代码。
+
+## 注意事项
+
+- 这些是**架构规则文档,不是 capability spec**,不放在 `openspec/specs/` 下。
+- 不参与 `openspec validate --strict`。
+- 由 `docs/knowledge-base/` 里的 PRD 引用,由 comate change 的 proposal/design 对齐。

package/skills/comate-gate/scaffold/docs/knowledge-base/README.md

@@ -1,47 +1,47 @@
-# 知识库 (Knowledge Base)
-
-本目录承载**需求(PRD)与第三方对接**的长期文档,与代码同仓库、同 PR 评审、同版本。
-
-## 文档体系与交接
-
-```
-docs/knowledge-base/requirements/
-  ├─ _templates/              PRD 模板
-  └─ <YYYYMMDD-功能名>/        一个功能一个目录,日期=该功能起始日   ──┐
-       ├─ PRD-001-<功能名>.md          产品需求文档                  │
-       ├─ PRD-001.gate.yaml            门禁状态(机器真相源)          │
-       ├─ PRD-001-REVIEW.md            门禁评审报告(人类可读)        │
-       └─ CHANGES-MAP.md               (多 change 时)功能项→change 映射 │
-                                                                    ├─→ /comate-gate (门禁+拆分)
-docs/knowledge-base/integrations/                                   │         ↓
-  第三方对接档案/索引 (跨需求长期存在)                              ──┘   comate changes
-```
-
-## PRD → comate 流程
-
-comate 采用**简化需求流**:只保留 **PRD**(产品需求文档),通过 `/comate-gate` 做两件事:
-
-1. **门禁**:审阅 PRD 质量、百分制评分、建阻断台账。阻断问题未清零,禁止建任何 change。
-2. **拆分**:按依赖/整体性/独立性/规模判定该 PRD 变成 1 或 N 个 comate change(粒度由用户定),逐个交给 `/comate-open`。
-
-PRD 门禁状态钉在同级 `PRD-<三位序号>.gate.yaml`(机器真相源,含 `gate_status` / `score` / `blocking_open` / `prd_hash` / `spawned_changes`)。评审报告为 `PRD-<三位序号>-REVIEW.md`(人类可读,含问题台账)。PRD 通过门禁后被改会因哈希漂移自动失效(`stale`),需重跑 gate。
-
+# 知识库 (Knowledge Base)
+
+本目录承载**需求(PRD)与第三方对接**的长期文档,与代码同仓库、同 PR 评审、同版本。
+
+## 文档体系与交接
+
+```
+docs/knowledge-base/requirements/
+  ├─ _templates/              PRD 模板
+  └─ <YYYYMMDD-功能名>/        一个功能一个目录,日期=该功能起始日   ──┐
+       ├─ PRD-001-<功能名>.md          产品需求文档                  │
+       ├─ PRD-001.gate.yaml            门禁状态(机器真相源)          │
+       ├─ PRD-001-REVIEW.md            门禁评审报告(人类可读)        │
+       └─ CHANGES-MAP.md               (多 change 时)功能项→change 映射 │
+                                                                    ├─→ /comate-gate (门禁+拆分)
+docs/knowledge-base/integrations/                                   │         ↓
+  第三方对接档案/索引 (跨需求长期存在)                              ──┘   comate changes
+```
+
+## PRD → comate 流程
+
+comate 采用**简化需求流**:只保留 **PRD**(产品需求文档),通过 `/comate-gate` 做两件事:
+
+1. **门禁**:审阅 PRD 质量、百分制评分、建阻断台账。阻断问题未清零,禁止建任何 change。
+2. **拆分**:按依赖/整体性/独立性/规模判定该 PRD 变成 1 或 N 个 comate change(粒度由用户定),逐个交给 `/comate-open`。
+
+PRD 门禁状态钉在同级 `PRD-<三位序号>.gate.yaml`(机器真相源,含 `gate_status` / `score` / `blocking_open` / `prd_hash` / `spawned_changes`)。评审报告为 `PRD-<三位序号>-REVIEW.md`(人类可读,含问题台账)。PRD 通过门禁后被改会因哈希漂移自动失效(`stale`),需重跑 gate。
+
 扇出的 comate change 内部用 proposal / design / tasks 承接 PRD 的功能项内容，PRD 直接作为 change 的源文档被 `sources track` 钉住。
-
+
 ## 命名约定
 
 - 功能目录：`<YYYYMMDD-功能名>/`
 - PRD：目录内 `PRD-<三位序号>-<功能名>.md`
 - gate 和评审报告：由脚本根据 PRD 路径自动生成，不手工命名。
-
-## 横向 (integrations/)
-
-- `integrations/` —— 第三方业务/接口对接档案与总索引,**跨多个需求长期存在**。
-- 单个 PRD 生命周期随功能上线收敛;本目录的内容长期维护,故独立放置。
-- PRD 的「第三方依赖」表应链接到 `integrations/<平台名>/README.md`。
-
-## 溯源与可追溯
-
-- PRD 顶部溯源块可选(若有更上游背景文档);没有上游时 PRD 是起点。
-- PRD 经门禁后扇出的 change 名记录在 `<PRD>.gate.yaml` 的 `spawned_changes` 字段,形成 PRD → change 的正向链。
-- 每个 change 的 `sources.manifest` 记录 PRD 路径与 sha256,形成 change → PRD 的反向链。
+
+## 横向 (integrations/)
+
+- `integrations/` —— 第三方业务/接口对接档案与总索引,**跨多个需求长期存在**。
+- 单个 PRD 生命周期随功能上线收敛;本目录的内容长期维护,故独立放置。
+- PRD 的「第三方依赖」表应链接到 `integrations/<平台名>/README.md`。
+
+## 溯源与可追溯
+
+- PRD 顶部溯源块可选(若有更上游背景文档);没有上游时 PRD 是起点。
+- PRD 经门禁后扇出的 change 名记录在 `<PRD>.gate.yaml` 的 `spawned_changes` 字段,形成 PRD → change 的正向链。
+- 每个 change 的 `sources.manifest` 记录 PRD 路径与 sha256,形成 change → PRD 的反向链。