refactor(agent-collaboration-kit): split stable core from project overrides

- Reorganize flat files into core/ templates/ examples/ scripts/ with VERSION
- Deduplicate: single-source state machine, three-round policy, acceptance signals
- Abstract orchestration in closed-loop.md with manual mode; move Orca commands to orca-adapter.md
- Add tasks.schema.json + validate_tasks.py (jsonschema or builtin rules, no hard deps)
- Add filled examples, concurrency write rule, kitVersion tracking; unify to Chinese

Co-authored-by: Cursor <cursoragent@cursor.com>

kits/agent-collaboration-kit/AGENTS-template.md

@@ -1,94 +0,0 @@
-# <Project Name> Agent Protocol
-
-本项目使用 `docs/agent-collaboration-kit/` 中的多 Agent 协作规范。本文填入本项目自己的路径、命令和权限边界。
-
-## Project Overview
-
-- Project: `<project_name>`
-- Stack: `<tech_stack>`
-- Main app command: `<run_command>`
-- Base URL: `<base_url>`
-- Task board: `tasks.yaml`
-
-## Roles
-
-| Role | Responsibility | Validation |
-|------|----------------|------------|
-| Product/Test Coordinator | Defines requirements, writes task evidence, runs black-box retest, marks verified | Browser/API/integration tests |
-| Developer Worker | Implements fixes/features, writes unit tests, runs build and white-box tests | Unit tests/build/local run |
-
-## Path Scoping
-
-| Path | Product/Test | Developer | Notes |
-|------|:------------:|:---------:|------|
-| `<spec_paths>` | R/W | Read-only | Product specs, API docs, plans |
-| `<integration_test_paths>` | R/W | Read-only | Browser/API regression |
-| `<test_records_path>` | R/W | Read-only | Run records |
-| `<source_paths>` | Read-only | R/W | Application source |
-| `<unit_test_paths>` | Read-only | R/W | Unit tests |
-| `<shared_config_templates>` | Read-only | R/W | Committable config templates |
-| `<local_config_paths>` | Read-only | Read-only | Local secrets/overrides |
-| `tasks.yaml` | R/W | Limited R/W | Product/Test owns `verified`; Developer may write implementation status/evidence |
-
-## Commands
-
-Developer verification:
-
-```bash
-<unit_test_command>
-<build_command>
-<local_run_command>
-```
-
-Product/Test verification:
-
-```bash
-<preflight_command>
-<api_smoke_command>
-<browser_regression_command>
-```
-
-## Task Status Lifecycle
-
-```text
-open -> dispatched -> fixed_by_dev -> retesting -> verified
-```
-
-Failure states:
-
-```text
-blocked
-failed_retest
-leftover
-```
-
-Rules:
-
-- `worker_done` is not completion. Product/Test must retest before `verified`.
-- Each task can be dispatched to Developer at most 3 rounds.
-- If still failing after 3 rounds, mark `leftover`, record evidence, and continue the next task.
-- Do not commit or push unless the user explicitly asks.
-
-## Orca Closed Loop
-
-Use `docs/agent-collaboration-kit/orca-closed-loop.md` when the user asks for supervised implementation/retest loops.
-
-Default loop:
-
-```text
-Product/Test records failure in tasks.yaml
-  -> Orca task-create
-  -> dispatch Developer Worker
-  -> wait worker_done/escalation/decision_gate
-  -> Product/Test retests
-  -> verified / failed_retest / leftover
-```
-
-## Definition Of Done
-
-A task is done only when:
-
-- Developer reports files modified and verification commands.
-- Product/Test verifies in the correct worktree/service.
-- Relevant build/test/browser/API checks pass.
-- `tasks.yaml` contains final evidence.

kits/agent-collaboration-kit/README.md

@@ -1,68 +1,77 @@
 # Agent Collaboration Kit
 
-这是一套可复制到其他项目的多 Agent 协作规范。它把“产品/测试负责定义与验收，开发负责实现与白盒验证，协调者用 Orca 做闭环调度”的经验抽成项目无关模板。
+一套可复用到其它项目的多 Agent 协作规范：**产品/测试负责定义与验收，开发负责实现与白盒验证，协调者做闭环调度**。
+
+当前版本见 `VERSION`。这不是 Agent Skill（无 `SKILL.md`），不由 skiff 安装，而是复制/引用到目标项目。
+
+---
 
 ## 适用场景
 
-- 项目需要多个 Agent 分工协作，而不是单个 Agent 从需求写到代码。
-- 需要明确区分规格、测试、实现、复测的责任边界。
-- 需要把测试失败项派发给开发 Agent，等 `worker_done` 后再由测试 Agent 复测。
-- 需要连续修复多个问题，并把三次仍未修好的问题留档。
+- 多个 Agent 分工协作，而非单个 Agent 从需求写到代码。
+- 需要区分规格、测试、实现、复测的责任边界。
+- 需要把失败项派发给开发 Agent，`worker_done` 后由测试 Agent 复测。
+- 需要连续修复多个问题，并把三轮仍未修好的问题留档。
 
-## 推荐目录
+---
 
-把本目录复制到目标项目：
+## 目录结构
 
 ```text
-docs/agent-collaboration-kit/
+agent-collaboration-kit/
+  VERSION                       # kit 版本，接入时记入项目
   README.md
-  roles-and-permissions.md
-  orca-closed-loop.md
-  task-board-template.yaml
-  prompt-templates.md
-  optimization-method.md
   adoption-checklist.md
+  core/                         # 稳定核心：跨项目通用，随 kit 升级，尽量别改
+    roles-and-permissions.md    #   角色/权限/状态机/完成定义（SSOT）
+    closed-loop.md              #   编排无关闭环 + 手动模式 + worktree 对齐
+    optimization-method.md      #   验收信号 + 三轮失败策略（SSOT）
+    prompt-templates.md         #   派发 prompt 模板
+    orca-adapter.md             #   Orca 具体命令（一种编排实现，可选）
+  templates/                    # 项目覆盖层：复制一次并填空
+    AGENTS.template.md
+    tasks.template.yaml
+    tasks.schema.json           #   任务板权威结构（跨语言）
+  examples/                     # 填好的最小可跑示例
+    AGENTS.example.md
+    tasks.example.yaml
+  scripts/
+    validate_tasks.py           # 校验 tasks.yaml（参考实现）
 ```
 
-目标项目还应在根目录保留一个项目级 `AGENTS.md`，引用本目录并填入项目自己的路径、测试命令和运行方式。
+**核心原则**：`core/` 是稳定核心，每个概念只定义一次；`templates/` 是项目覆盖层。二者分离，让 kit 升级和项目定制互不干扰。
 
-## 核心原则
+---
 
-1. **事实源持久化**：任务、bug、验收证据写入任务板文件，不依赖聊天上下文。
-2. **角色隔离**：Product/Test Agent 只定义和验证；Developer Agent 只实现和自测。
-3. **worker_done 不等于完成**：开发 Agent 声称修好后，必须由 Product/Test Agent 黑盒复测。
-4. **最多三轮自动修复**：同一问题三轮仍未通过，记录为遗留项，然后继续处理下一个问题。
-5. **服务与 worktree 对齐**：复测前确认服务、构建产物、分支和工作树一致，避免假通过或假失败。
+## 分发方式（二选一）
 
-## 快速接入步骤
+### 方式 A：引用稳定核心（推荐，可升级）
 
-1. 复制本目录到目标项目。
-2. 基于 `roles-and-permissions.md` 在目标项目根目录创建或更新 `AGENTS.md`。
-3. 基于 `task-board-template.yaml` 创建 `tasks.yaml`。
-4. 在 `AGENTS.md` 中写清：
-   - 项目运行命令
-   - 单元测试命令
-   - 构建命令
-   - 集成/浏览器测试命令
-   - Product/Test 与 Developer 的路径权限
-5. 使用 `orca-closed-loop.md` 的流程派发修复。
-6. 按 `optimization-method.md` 执行三轮失败留档和节奏优化。
+`core/` + `scripts/` 通过 symlink / git submodule / sparse checkout 映射到项目 `docs/agent-collaboration-kit/`；项目只维护自己的 `AGENTS.md`、`tasks.yaml`。kit 升级时稳定核心自动生效，项目定制不受影响。
 
-## 建议的默认口令
+### 方式 B：整份复制（简单，手动升级）
+
+整目录复制到 `docs/agent-collaboration-kit/`。**务必**在项目 `AGENTS.md` 与 `tasks.yaml` 的 `kitVersion` 记录来源版本，日后照 `VERSION` diff 升级 `core/`。
+
+无论哪种方式，项目的 `AGENTS.md` 只填差异（路径、命令、handle），不复制 `core/` 内容。
+
+---
+
+## 快速接入
+
+1. 选定分发方式，把 kit 放到项目 `docs/agent-collaboration-kit/`。
+2. 复制 `templates/AGENTS.template.md` → 项目根 `AGENTS.md`，填项目差异，记 `kitVersion`。
+3. 复制 `templates/tasks.template.yaml` → 项目根 `tasks.yaml`，填 `project` 与首个任务。
+4. 跑 `python3 docs/agent-collaboration-kit/scripts/validate_tasks.py tasks.yaml` 确认结构。
+5. 按 `core/closed-loop.md` 跑闭环（Orca 见 `core/orca-adapter.md`，无 Orca 用手动模式）。
+6. 逐项对照 `adoption-checklist.md`。
+
+参考 `examples/` 里填好的 `AGENTS.example.md` 与 `tasks.example.yaml`。
+
+---
+
+## 默认口令
 
 ```text
 用 Agent 协作闭环处理 tasks.yaml 里的未通过项；每个问题最多派发开发 Agent 修三轮，三轮仍不过就记录为遗留，然后继续下一个。
 ```
-
-## 与具体项目解耦
-
-本工具包使用占位符表达项目差异：
-
-- `<repo_path>`：仓库根目录
-- `<dev_worktree>`：开发 Agent 工作树
-- `<base_url>`：待测服务地址
-- `<test_commands>`：项目测试命令
-- `<source_paths>`：开发可改源码路径
-- `<spec_paths>`：产品/测试可改规格与测试路径
-
-复制到新项目后，应先替换这些占位符，再开始调度。

kits/agent-collaboration-kit/VERSION

@@ -0,0 +1 @@
+0.2.0

kits/agent-collaboration-kit/adoption-checklist.md

@@ -1,74 +1,59 @@
-# Adoption Checklist
+# 接入清单
 
-复制本工具包到新项目后，按这份清单接入。
+把本工具包引用/复制到新项目后，按此清单接入。术语与规则详见 `core/`。
 
-## 1. 项目级规范
+## 1. 分发与版本
 
-- [ ] 根目录存在 `AGENTS.md`。
-- [ ] `AGENTS.md` 引用 `docs/agent-collaboration-kit/`。
-- [ ] 写清项目简介和技术栈。
-- [ ] 写清本地运行命令。
-- [ ] 写清构建命令。
-- [ ] 写清单元测试命令。
-- [ ] 写清集成测试或浏览器测试命令。
+- [ ] 选定分发方式（README §「分发方式」A 引用 / B 复制）。
+- [ ] kit 放到 `docs/agent-collaboration-kit/`。
+- [ ] 项目 `AGENTS.md` 与 `tasks.yaml` 记录 `kitVersion`（对齐 kit 根 `VERSION`）。
 
-## 2. 路径权限
+## 2. 项目级规范（覆盖层）
 
-- [ ] Product/Test 可写规格路径：`<spec_paths>`。
-- [ ] Product/Test 可写集成测试路径：`<integration_test_paths>`。
-- [ ] Developer 可写源码路径：`<source_paths>`。
-- [ ] Developer 可写单元测试路径：`<unit_test_paths>`。
-- [ ] 本地私有配置标记为只读或不提交。
-- [ ] 明确 `tasks.yaml` 状态字段谁可以改。
+- [ ] 由 `templates/AGENTS.template.md` 生成项目根 `AGENTS.md`。
+- [ ] `AGENTS.md` 引用 `docs/agent-collaboration-kit/core/`，不复制其内容。
+- [ ] 填清项目简介、技术栈、运行/构建/单测/集成测试命令。
 
-## 3. 任务板
+## 3. 路径权限
 
-- [ ] 从 `task-board-template.yaml` 创建项目根目录 `tasks.yaml`。
+- [ ] 填实际的 Product/Test 可写路径（规格、集成测试、复测记录）。
+- [ ] 填实际的 Developer 可写路径（源码、单元测试、配置模板）。
+- [ ] 本地私有配置标记只读或不提交。
+- [ ] 确认 `tasks.yaml` 只有 Coordinator 写（见 `core/roles-and-permissions.md`）。
+
+## 4. 任务板
+
+- [ ] 由 `templates/tasks.template.yaml` 生成项目根 `tasks.yaml`。
 - [ ] 替换 `<project_name>`、`<repo_path>`、`<base_url>`、`<dev_worktree>`。
-- [ ] 至少添加一个示例任务，验证字段结构够用。
-- [ ] 约定状态：`open`、`dispatched`、`fixed_by_dev`、`retesting`、`verified`、`leftover`。
+- [ ] 至少加一个真实任务，验收写成可观测信号（见 `core/optimization-method.md` §1）。
+- [ ] 跑 `scripts/validate_tasks.py tasks.yaml` 通过。
 
-## 4. Orca 编排
+## 5. 编排
 
-- [ ] `orca status --json` 可用。
-- [ ] `orca terminal list --json` 能看到 Coordinator 终端。
-- [ ] 能创建或复用 Developer Worker。
-- [ ] 决定默认使用当前 worktree 还是隔离 worktree。
-- [ ] 验证 `worker_done` 能发回 Coordinator。
+- [ ] 决定用 Orca（`core/orca-adapter.md`）还是手动模式（`core/closed-loop.md`）。
+- [ ] Orca：`orca status`、`terminal list` 可用，`worker_done` 能发回 Coordinator。
+- [ ] 决定用当前 worktree 还是隔离 worktree。
 
-## 5. 验证命令
+## 6. 验证命令
 
-- [ ] Product/Test 有黑盒验证命令。
-- [ ] Developer 有白盒验证命令。
-- [ ] 构建产物和服务启动命令写清楚。
-- [ ] 浏览器测试的 `BASE_URL` 写清楚。
-- [ ] 复测前能确认服务来自正确 worktree。
+- [ ] Product/Test 有黑盒验证命令，Developer 有白盒验证命令。
+- [ ] 构建产物与服务启动命令写清。
+- [ ] 浏览器测试 `BASE_URL` 写清，复测前能确认服务来自正确 worktree。
 
-## 6. 三轮失败策略
+## 7. 三轮失败策略
 
-- [ ] 每个任务记录 `rounds` 或等效 evidence。
-- [ ] 三轮失败后标记 `leftover`。
-- [ ] `leftover` 不阻塞继续处理其他任务。
-- [ ] 最终报告列出所有 `leftover` 和最后失败证据。
+- [ ] 每个任务记录 `dispatch.rounds`。
+- [ ] 三轮失败标记 `leftover` 并填 `resolution.leftoverReason`。
+- [ ] `leftover` 不阻塞其它任务；最终报告列出所有 `leftover` 与最后失败证据。
 
-## 7. 第一次试运行
+## 8. 第一次试运行
 
-推荐选择一个低风险 bug 跑完整流程：
-
-1. Product/Test 写入 `tasks.yaml`。
-2. 创建 Orca task。
-3. 派发 Developer Worker。
-4. 等待 `worker_done`。
-5. Product/Test 复测。
-6. 更新 `tasks.yaml`。
-7. 输出总结。
-
-试运行结束后，检查是否出现以下问题：
+选一个低风险 bug 跑完整闭环，结束后检查是否出现：
 
 - Developer 修改了越权路径。
 - worker_done 没有验证证据。
 - Product/Test 复测到了旧服务。
 - 任务板字段不够记录失败原因。
-- 三轮失败策略没有被执行。
+- 三轮失败策略没被执行。
 
-把发现的问题回写到项目 `AGENTS.md` 或本工具包的项目副本中。
+把发现的问题回写到项目 `AGENTS.md`；若属通用问题，回流到 kit 的 `core/` 并升 `VERSION`。

kits/agent-collaboration-kit/core/closed-loop.md

@@ -0,0 +1,132 @@
+# 闭环流程（稳定核心，编排无关）
+
+本文件定义**与具体编排工具无关**的协作闭环。运行时调度可以用 Orca（见 `orca-adapter.md`），也可以手动跑（见下方「手动模式」）。
+
+原则：调度消息只是运行时载体，**所有结论都必须回写到 `tasks.yaml`**（事实源），不要把消息当最终记录。
+
+---
+
+## 编排抽象
+
+无论用什么工具，闭环都由这几个能力组成：
+
+| 抽象动作 | 含义 | Orca 实现 | 手动实现 |
+|----------|------|-----------|----------|
+| `prepare(task)` | 把任务和验收标准写进 `tasks.yaml` | 同左 | 同左 |
+| `dispatch(task, worker)` | 把任务连同上下文交给 Developer | `orca orchestration dispatch` | 复制 prompt 到 Developer 终端/会话 |
+| `wait()` | 等待 `worker_done` / `escalation` / `decision_gate` | `orca orchestration check --wait` | 人工等待 Developer 回报 |
+| `retest(task)` | Coordinator 独立黑盒复测 | 同左 | 同左 |
+| `writeback(task, result)` | 把复测结果写回 `tasks.yaml` | 同左 | 同左 |
+
+派发用的 prompt 见 `prompt-templates.md`。状态流转见 `roles-and-permissions.md` §「任务状态机」。
+
+---
+
+## 标准闭环
+
+```text
+Product/Test 发现或读取 open 任务
+  -> prepare：写/补全 tasks.yaml 验收标准
+  -> dispatch 给 Developer Worker
+  -> wait：worker_done / escalation / decision_gate
+  -> retest：Coordinator 构建并独立复测
+  -> 通过：writeback verified
+  -> 失败：writeback failed_retest，追加证据，最多再派发两轮
+  -> 累计三轮失败：writeback leftover，继续下一个任务
+```
+
+一次派发只修一个明确问题（细则见 `optimization-method.md` §「每轮派发只修一个明确问题」）。
+
+---
+
+## 手动模式（无 Orca）
+
+没有编排工具时，闭环不变，只是 `dispatch` / `wait` 由人工承担：
+
+1. Coordinator 在 `tasks.yaml` 写好任务和验收标准。
+2. 用 `prompt-templates.md` 的初始派发模板生成 prompt，手动发给 Developer（另一个会话/终端/人）。
+3. Developer 完成后按 worker_done 模板回报（可直接贴回 Coordinator 会话）。
+4. Coordinator 独立复测，回写 `tasks.yaml`。
+5. 失败则用「复测失败再派发模板」继续，最多三轮。
+
+手动模式下同样遵守：worker_done 不等于完成、只有 Coordinator 写 `tasks.yaml`、三轮失败留档。
+
+---
+
+## worker_done 后复测（编排无关）
+
+即使 worker_done 写了"全部通过"，Coordinator 仍必须独立复测：
+
+```bash
+git status --short
+<test_commands>
+curl -s <base_url>/health-or-summary
+```
+
+浏览器复测建议记录：
+
+```text
+BASE_URL:
+page:
+steps:
+expected:
+actual:
+snapshot evidence:
+```
+
+---
+
+## 服务与 worktree 对齐（防假通过/假失败）
+
+复测前记录运行环境：
+
+```bash
+pwd
+git rev-parse --abbrev-ref HEAD
+git rev-parse --short HEAD
+```
+
+```text
+serverPid:
+serverCommand:
+BASE_URL:
+frontendDir:
+worktreePath:
+```
+
+如果开发在 `<dev_worktree>` 修复，但服务跑的是另一个 worktree，必须**停止并重启正确服务**后再测。长跑服务或静态前端尤其要确认加载的是最新构建产物。
+
+---
+
+## 结果回写
+
+回写 `tasks.yaml` 时按状态填写（字段结构见 `templates/tasks.schema.json`）：
+
+```yaml
+# 通过
+status: verified
+resolution:
+  verifiedAt: "<timestamp>"
+  evidence:
+    verification: "<commands passed>"
+    browser: "<snapshot or API evidence>"
+```
+
+```yaml
+# 失败但未满三轮
+status: failed_retest
+dispatch:
+  rounds:
+    - round: 1
+      result: failed
+      evidence: "<latest evidence>"
+```
+
+```yaml
+# 累计三轮失败
+status: leftover
+resolution:
+  leftoverReason: "failed after 3 supervised developer rounds"
+  evidence:
+    final: "<latest failing evidence>"
+```

kits/agent-collaboration-kit/core/optimization-method.md

@@ -0,0 +1,148 @@
+# 优化方法（稳定核心）
+
+减少"开发声称完成但复测不过"的循环成本。本文件是**验收信号写法**和**三轮失败策略**的 SSOT，其它文件引用这里。
+
+复测步骤与环境对齐见 `closed-loop.md`；状态机与完成定义见 `roles-and-permissions.md`。
+
+---
+
+## 1. 先把验收写成可观测信号（SSOT）
+
+不要只写"页面可用""体验更好"。每个任务至少写三类信号：
+
+| 类型 | 示例 |
+|------|------|
+| 可见文本 | 页面出现 `确认应用标签`、`取消`、`将修改` |
+| API 结果 | `POST /api/...` 返回 `code=0` 且字段存在 |
+| 交互结果 | 点击按钮后出现确认区；取消后不触发写入 |
+
+好的验收：
+
+```text
+点击"预览变更"后，页面必须出现 API 返回的 diff 行：
+- title
+- 修改前值
+- 修改后值
+- coverChanged 提示
+```
+
+不好的验收：
+
+```text
+预览功能正常。
+```
+
+---
+
+## 2. worker_done 必须带证据，不带结论
+
+Developer Worker 的 `worker_done` 应报告：改了哪些文件、跑了哪些命令、自己如何复现验收路径、仍可能有的风险。
+
+不要写：
+
+```text
+已完成，应该可以了。
+```
+
+要写：
+
+```text
+修改 web/app/fix/page.tsx。已运行 npm run build、go test ./...。
+手测 /fix?fileId=1：搜索、选择候选、预览、确认区都可见。
+风险：未执行真实写文件 apply。
+```
+
+---
+
+## 3. Product/Test 只信自己的复测
+
+即使 worker_done 写了"全部通过"，Coordinator 仍必须独立复测。完整复测步骤与 worktree/服务对齐见 `closed-loop.md`。这可避免三类假通过：测错服务实例、测到旧构建产物、开发只验证静态文本没验证真实交互。
+
+---
+
+## 4. 三轮失败策略（SSOT）
+
+每个任务最多自动派发三轮：
+
+```text
+round 1: 常规修复
+round 2: 带复测失败证据的定向修复
+round 3: 明确指出重复失败点，要求 worker 自己复现完整路径
+failed after round 3: 标记 leftover，继续下一个任务
+```
+
+三轮失败后不要继续消耗同一个 worker。常见原因：验收标准需要重新设计、Worker 对问题模型理解错了、UI 自动化与实际浏览器状态有差异、需要人工观察或调试工具介入。
+
+留档字段（结构见 `templates/tasks.schema.json`）：
+
+```yaml
+status: leftover
+resolution:
+  leftoverReason: "failed after 3 supervised developer rounds"
+dispatch:
+  rounds:
+    - round: 1
+      result: failed
+      evidence: "<why failed>"
+    - round: 2
+      result: failed
+      evidence: "<why failed>"
+    - round: 3
+      result: failed
+      evidence: "<why failed>"
+```
+
+---
+
+## 5. 任务排序
+
+1. P0 阻塞主流程。
+2. P1 高频用户路径。
+3. P1/P2 体验改进。
+4. 重构和内部质量。
+
+三轮失败的 P0 可以留档，但发布前需人工决策：降级范围、改验收标准、换新 Agent / 新 worktree 重做、人工修复。
+
+---
+
+## 6. 每轮派发只修一个明确问题
+
+不要一次让 Developer Worker 修太多失败项，除非它们共享同一根因：
+
+```text
+one dispatch = one bug = one acceptance path
+```
+
+优点：复测更快、失败原因更清楚、三轮失败留档更准确。
+
+---
+
+## 7. 把失败证据写给下一轮 worker
+
+第二轮以后，派发 prompt 应突出"上一轮为什么没过"，而非重复原始描述。模板见 `prompt-templates.md` §「复测失败再派发模板」。
+
+---
+
+## 8. 优先让测试可执行化
+
+如果某个问题需要多轮修复，说明它值得沉淀成自动化检查。优先级：
+
+1. API smoke。
+2. 浏览器脚本或 case 文档。
+3. 单元测试。
+4. 人工检查清单。
+
+目标不是全部自动化，而是把最容易反复误判的路径自动化。
+
+---
+
+## 9. 结束条件
+
+一轮闭环结束时，必须能回答：
+
+- 哪些任务 verified？哪些 leftover？
+- 每个 leftover 失败了几轮？最后一轮失败证据是什么？
+- 当前工作树有哪些未提交改动？
+- 是否还有 open / failed_retest 未处理？
+
+答不清楚，闭环就还没结束。

kits/agent-collaboration-kit/core/orca-adapter.md

@@ -0,0 +1,126 @@
+# Orca 适配器（稳定核心，一种编排实现）
+
+Orca orchestration 是运行时调度层的一种实现。闭环流程本身与工具无关（见 `closed-loop.md`）；本文件只提供 Orca 的具体命令。没有 Orca 时用 `closed-loop.md` §「手动模式」。
+
+所有结论仍以 `tasks.yaml` 为准，Orca 消息不是最终记录。
+
+---
+
+## 何时用 Orca 编排
+
+用：需要监督、等待结果、闭环修复、三轮重试；有多个可独立派发的任务；需要 `worker_done` 后再复测。
+
+不用：单次问答；用户只要求完整 handoff 不需监督；不需要复测的小改动。
+
+---
+
+## 运行前检查
+
+```bash
+orca status --json
+orca terminal list --json
+orca orchestration task-list --json
+orca orchestration inbox --limit 20 --json
+```
+
+确认：Orca runtime 可达；Coordinator 与 Developer Worker 终端都存在；Developer 在正确 worktree；当前没有冲突的活跃编排任务。
+
+---
+
+## 创建父任务
+
+```bash
+orca orchestration task-create --spec "$(cat <<'EOF'
+Goal: Complete <release_or_feature> with supervised Product/Test -> Developer loop.
+
+Coordinator: owns task board, black-box tests, retest, final verification.
+Developer: owns implementation and white-box verification.
+
+Policy:
+- Each issue can be dispatched at most 3 rounds.
+- If still failing after 3 rounds, record as leftover and continue next issue.
+- worker_done is not final completion.
+EOF
+)" --json
+```
+
+## 创建子任务
+
+```bash
+orca orchestration task-create --parent <parent_task_id> --spec "$(cat <<'EOF'
+Fix <task_id>: <title>
+
+Repository:
+- Path: <repo_path>
+- Worktree: <dev_worktree>
+
+Read: AGENTS.md, tasks.yaml, <relevant_spec_or_test_doc>
+Failure evidence: <copy latest Product/Test evidence>
+Acceptance: <copy expected behavior + verification commands>
+
+Constraints:
+- Follow AGENTS.md path scope.
+- Do not write tasks.yaml, do not mark verified.
+- Do not commit or push unless user asks.
+EOF
+)" --json
+```
+
+---
+
+## 派发给 Developer Worker
+
+终端是 Orca 可识别的 Agent CLI 时：
+
+```bash
+orca orchestration dispatch --task <task_id> --to <developer_handle> --inject --json
+```
+
+不能 `--inject` 时，先登记 dispatch，再手动投递 `prompt-templates.md` §1 的初始派发 prompt：
+
+```bash
+orca orchestration dispatch --task <task_id> --to <developer_handle> --json
+orca terminal send --terminal <developer_handle> --text "$(cat <<'EOF'
+<粘贴 prompt-templates.md §1 初始派发模板，已填占位符>
+EOF
+)" --enter --json
+```
+
+---
+
+## 等待结果
+
+```bash
+orca orchestration check \
+  --terminal <coordinator_handle> \
+  --wait \
+  --types worker_done,escalation,decision_gate \
+  --timeout-ms 900000 \
+  --json
+```
+
+等待超时不等于失败。长任务可继续等待，或检查 worker 终端活性。
+
+---
+
+## Developer 回报 worker_done
+
+字段含义见 `prompt-templates.md` §3：
+
+```bash
+orca orchestration send \
+  --to <coordinator_handle> \
+  --type worker_done \
+  --subject "<task_id> fix ready round <n>" \
+  --body "<修了什么。跑了哪些验证。如何复现。还有什么风险。>" \
+  --payload '{
+    "taskId": "<orca_task_id>",
+    "dispatchId": "<orca_dispatch_id>",
+    "filesModified": ["<file_a>", "<file_b>"],
+    "verification": ["<command_a>: passed", "<command_b>: passed"],
+    "risk": "<remaining risk or none>"
+  }' \
+  --json
+```
+
+收到 worker_done 后，Coordinator 按 `closed-loop.md` 独立复测并回写 `tasks.yaml`。

kits/agent-collaboration-kit/core/prompt-templates.md

@@ -0,0 +1,106 @@
+# 派发 Prompt 模板（稳定核心）
+
+用于 Coordinator 给 Developer Worker 派发任务。复制时替换尖括号占位符。这些模板与编排工具无关：Orca 模式用 `orca-adapter.md` 的命令投递，手动模式直接把文本发给 Developer。
+
+---
+
+## 1. 初始派发模板
+
+```text
+你现在接到一个受监督的协作任务。请在 <dev_worktree> 开发工作树内完成。
+
+任务：
+- 修复 <task_id>: <task_title>
+
+请先读取：
+- AGENTS.md
+- tasks.yaml
+- <relevant_spec_or_test_doc>
+
+当前失败证据：
+<copy latest Product/Test evidence>
+
+验收标准（可观测信号，见 optimization-method.md §1）：
+1. <expected behavior 1>
+2. <expected behavior 2>
+3. <expected behavior 3>
+
+约束：
+- 只修改 Developer 可写路径（见 AGENTS.md 权限表）。
+- 不要修改 Product/Test 负责的规格和集成测试文件，除非任务明确要求。
+- 不要写 tasks.yaml，不要标记 verified。
+- 不要提交或推送，除非用户明确要求。
+- 最小 diff，避免无关重构。
+
+完成前必须运行：
+- <test command 1>
+- <test command 2>
+
+完成后回报一次 worker_done（格式见 §4）。如果阻塞，请发送 escalation 或 ask。
+```
+
+---
+
+## 2. 复测失败再派发模板
+
+```text
+第 <n> 轮复测未通过，请继续修 <task_id>。
+
+上一轮开发声称：
+<worker_done summary>
+
+Product/Test 独立复测结果：
+- 运行命令：<commands>
+- 失败页面/API：<page or endpoint>
+- 仍缺失：<missing expected checks>
+- 实际观察：<actual evidence>
+
+关键提示：
+- 不要只满足静态文案，必须满足交互后的真实状态。
+- 如果后端/API 正常而 UI 不更新，请优先排查事件链、状态重置、异步请求、构建产物和服务 worktree。
+- 修复后请自己用浏览器或脚本复现 Product/Test 的完整步骤。
+
+验收不变：
+<copy acceptance criteria>
+
+完成后回报 worker_done，subject 使用："<task_id> fix ready round <n>"
+```
+
+---
+
+## 3. Developer Worker worker_done 回报格式（通用）
+
+无论 Orca 还是手动，回报都应包含以下字段：
+
+```text
+subject: <task_id> fix ready round <n>
+filesModified: [<file_a>, <file_b>]
+verification:
+  - <command_a>: passed
+  - <command_b>: passed
+reproduce: 我如何复现验收路径 <steps>
+risk: <remaining risk or none>
+```
+
+Orca 模式下用 `orca-adapter.md` §「Developer 回报 worker_done」的命令发送同样的字段。
+
+---
+
+## 4. Coordinator 最终报告模板
+
+```text
+本轮闭环完成。
+
+已验证：
+- <task_id>: <what passed>
+
+遗留：
+- <task_id>: 三轮仍未通过，已记录为 leftover。最后失败证据：<evidence>
+
+验证命令：
+- <command>: passed
+
+工作树状态：
+- <repo_path>: <git status summary>
+- <dev_worktree>: <git status summary>
+```

kits/agent-collaboration-kit/core/roles-and-permissions.md

@@ -1,6 +1,10 @@
-# Roles And Permissions
+# 角色与权限（稳定核心）
 
-本文件定义多 Agent 协作的责任边界。目标是让每个 Agent 只处理自己能验证的事情，减少上下文污染和越权修改。
+本文件是**角色模型、路径权限、任务状态机、完成定义**的单一事实源（SSOT）。其它文件只引用本文件，不重复定义。
+
+目标：让每个 Agent 只处理自己能验证的事情，减少上下文污染和越权修改。
+
+---
 
 ## 角色模型
 
@@ -10,9 +14,11 @@
 | Developer Worker | 实现修复、写单元测试、运行构建和白盒验证 | 单元测试、类型检查、构建、本地运行 | 修改产品规格、标记 verified、绕过测试声称完成 |
 | User / Decision Owner | 决定范围、优先级、阻塞项是否继续 | 审阅报告和遗留清单 | 直接替代复测证据 |
 
+---
+
 ## 路径权限模板
 
-目标项目应在 `AGENTS.md` 中填入实际路径。
+目标项目在自己的 `AGENTS.md` 中填入实际路径（见 `templates/AGENTS.template.md`）。
 
 | 路径 | Product/Test | Developer | 说明 |
 |------|:------------:|:---------:|------|
@@ -23,40 +29,11 @@
 | `<unit_test_paths>` | Read-only | R/W | 单元测试 |
 | `<shared_config_templates>` | Read-only | R/W | 可提交配置模板 |
 | `<local_config>` | Read-only | Read-only | 本地私有配置，不提交 |
-| `tasks.yaml` | R/W | Limited R/W | 任务事实源；Developer 可写实现状态和证据，Product/Test 写 verified |
+| `tasks.yaml` | R/W | Read-only | 见下方「任务板写入约定」 |
 
-## Product/Test Coordinator 工作流
+---
 
-1. 读取用户目标、项目规格、任务板。
-2. 用黑盒方式复现问题或验证需求。
-3. 在 `tasks.yaml` 写入任务：
-   - 复现步骤
-   - 预期结果
-   - 实际结果
-   - 证据
-   - 验收命令或验收页面
-4. 创建 Orca 编排任务并派发 Developer Worker。
-5. 等待 `worker_done` / `escalation` / `decision_gate`。
-6. 重新构建和复测。
-7. 通过则标记 `verified`；失败则追加证据并继续派发，最多三轮。
-8. 三轮失败则标记为遗留项，继续下一个任务。
-
-## Developer Worker 工作流
-
-1. 读取 `AGENTS.md`、`tasks.yaml` 和相关规格。
-2. 只修改 Developer 可写路径。
-3. 做最小正确修改，避免顺手重构。
-4. 为非平凡逻辑补充或更新单元测试。
-5. 运行项目要求的验证命令。
-6. 完成后发送一次 `worker_done`，包含：
-   - 修改文件
-   - 验证命令和结果
-   - 剩余风险
-7. 不标记 `verified`，也不提交或推送，除非用户明确要求。
-
-## 状态机
-
-推荐 `tasks.yaml` 使用以下状态：
+## 任务状态机（SSOT）
 
 ```text
 open
@@ -71,7 +48,7 @@ open
 ```text
 dispatched     -> blocked
 fixed_by_dev   -> failed_retest -> dispatched
-failed_retest x3 -> leftover
+failed_retest（累计 3 轮） -> leftover
 ```
 
 状态定义：
@@ -80,19 +57,34 @@ failed_retest x3 -> leftover
 |------|--------|------|
 | `open` | Product/Test | 已发现，等待处理 |
 | `dispatched` | Product/Test | 已派发给开发 Agent |
-| `blocked` | Product/Test 或 Developer | 需要用户决策或外部条件 |
-| `fixed_by_dev` | Developer | 开发声称已修复并提供验证 |
+| `fixed_by_dev` | Product/Test（据 worker_done 回写） | 开发声称已修复并提供验证 |
 | `retesting` | Product/Test | 正在复测 |
 | `failed_retest` | Product/Test | 复测失败，可继续派发 |
 | `verified` | Product/Test | 复测通过 |
-| `leftover` | Product/Test | 三轮仍未通过，留给人工或专项处理 |
+| `blocked` | Product/Test | 需要用户决策或外部条件 |
+| `leftover` | Product/Test | 累计 3 轮仍未通过，留给人工或专项处理 |
 
-## 完成定义
+三轮失败的处理细则见 `optimization-method.md` §「三轮失败策略」。
+
+---
+
+## 任务板写入约定（并发安全）
+
+`tasks.yaml` 是持久事实源，为避免多 Worker 并发写冲突：
+
+- **只有 Coordinator 写 `tasks.yaml`**。Developer Worker 对它是只读的。
+- Developer 的实现状态、证据通过 `worker_done` 消息回传，由 Coordinator 落盘。
+- 每次写入前先读最新内容，写入后更新顶层 `updatedAt`。
+- 单次写入应是一个任务的一次状态跃迁，避免整表批量重写。
+
+---
+
+## 完成定义（Definition of Done）
 
 一个任务只有同时满足以下条件，才能标记 `verified`：
 
 - Developer 已提供修改文件和验证证据。
-- Product/Test 在正确 worktree 和正确服务实例上复测。
+- Product/Test 在正确 worktree 和正确服务实例上复测（对齐检查见 `closed-loop.md`）。
 - 相关单元测试、构建、集成或浏览器检查通过。
 - `tasks.yaml` 中记录了复测证据。
 - 用户可见行为符合验收标准。

kits/agent-collaboration-kit/examples/AGENTS.example.md

@@ -0,0 +1,64 @@
+# notes-web Agent 协作协议（示例）
+
+> 本项目基于 agent-collaboration-kit v0.2.0。
+> 稳定规范引用 `docs/agent-collaboration-kit/core/`，本文件只填项目差异。
+
+## 项目概览
+
+- 项目：`notes-web`
+- 技术栈：`TypeScript + React (Vite) + Go`
+- 运行命令：`npm run dev`（前端）、`go run ./server`（后端）
+- Base URL：`http://localhost:5173`
+- 任务板：`tasks.yaml`
+
+## 稳定规范（引用，不重复）
+
+- 角色 / 权限 / 状态机 / 完成定义：`docs/agent-collaboration-kit/core/roles-and-permissions.md`
+- 闭环流程（含手动模式、worktree 对齐）：`docs/agent-collaboration-kit/core/closed-loop.md`
+- 优化方法（验收信号、三轮策略）：`docs/agent-collaboration-kit/core/optimization-method.md`
+- 派发 prompt 模板：`docs/agent-collaboration-kit/core/prompt-templates.md`
+- Orca 编排命令：`docs/agent-collaboration-kit/core/orca-adapter.md`
+
+## 路径权限
+
+| 路径 | Product/Test | Developer | 说明 |
+|------|:------------:|:---------:|------|
+| `docs/spec/**` | R/W | Read-only | 产品规格 |
+| `tests/browser/**` | R/W | Read-only | 浏览器回归用例 |
+| `.qa-records/**` | R/W | Read-only | 复测记录（gitignore） |
+| `web/**`、`server/**` | Read-only | R/W | 应用源码 |
+| `**/*_test.go`、`web/**/*.test.tsx` | Read-only | R/W | 单元测试 |
+| `config/*.example.*` | Read-only | R/W | 可提交配置模板 |
+| `.env`、`config/local.*` | Read-only | Read-only | 本地私有配置 |
+| `tasks.yaml` | R/W | Read-only | 只有 Coordinator 写 |
+
+## 命令
+
+Developer 白盒验证：
+
+```bash
+npm run build
+go test ./...
+npm run dev   # 本地起前端
+```
+
+Product/Test 黑盒验证：
+
+```bash
+curl -s http://localhost:5173/api/health
+curl -s -X POST http://localhost:5173/api/fix/preview -d @fixtures/preview.json
+# 浏览器回归：tests/browser/cases/*.md
+```
+
+任务板校验：
+
+```bash
+python3 docs/agent-collaboration-kit/scripts/validate_tasks.py tasks.yaml
+```
+
+## 硬规则（其余见 core/）
+
+- `worker_done` 不等于完成，必须独立复测后才能 `verified`。
+- 只有 Coordinator 写 `tasks.yaml`。
+- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续。
+- 不提交或推送，除非用户明确要求。

kits/agent-collaboration-kit/examples/tasks.example.yaml

@@ -0,0 +1,113 @@
+# 填好的最小示例（虚构的 notes-web 项目）。可用 scripts/validate_tasks.py 校验通过。
+version: 1
+updatedAt: "2026-07-06T09:40:00+08:00"
+source: "Product/Test Agent"
+kitVersion: "0.2.0"
+project:
+  name: "notes-web"
+  repoPath: "/home/dev/notes-web"
+  baseUrl: "http://localhost:5173"
+  devWorktree: "/home/dev/notes-web-wt/fix-preview"
+
+summary:
+  verified: ["BUG-002"]
+  open: []
+  failedRetest: []
+  leftovers: ["BUG-003"]
+
+tasks:
+  - id: "BUG-002"
+    type: "bug"
+    title: "预览变更点击后不显示 diff 行"
+    priority: "P0"
+    status: "verified"
+    assignee: "developer"
+    component: "web/app/fix/page.tsx"
+    specRefs:
+      - "docs/spec/fix-preview.md#preview"
+    testRefs:
+      - "tests/browser/cases/01-preview.md"
+    description: >
+      用户在 /fix 页点击“预览变更”后，确认区不渲染 API 返回的 diff。
+    stepsToReproduce:
+      - "打开 /fix?fileId=1"
+      - "搜索并选择候选项"
+      - "点击“预览变更”"
+    expected: >
+      确认区出现 title、修改前值、修改后值、coverChanged 提示四行。
+    actual: >
+      API 返回 code=0，但页面确认区为空。
+    evidence:
+      browser: "确认区 DOM 为空，无 diff 行"
+      api: "POST /api/fix/preview -> code=0, 含 diff 字段"
+      logs: "无报错"
+    verification:
+      commands:
+        - "npm run build"
+        - "curl -s -X POST localhost:5173/api/fix/preview -d @fixtures/preview.json"
+      browser:
+        page: "/fix?fileId=1"
+        checks:
+          - "预览后出现 4 行 diff：title/before/after/coverChanged"
+    dispatch:
+      taskId: "orca-task-88"
+      dispatchId: "orca-disp-91"
+      worker: "dev-worker-1"
+      rounds:
+        - round: 1
+          result: failed
+          evidence: "只渲染了 title，缺少 before/after/coverChanged"
+        - round: 2
+          result: passed
+          evidence: "复测 4 行 diff 全部出现，取消不触发写入"
+    resolution:
+      fixedBy: "dev-worker-1"
+      verifiedAt: "2026-07-06T09:38:00+08:00"
+      leftoverReason: null
+
+  - id: "BUG-003"
+    type: "bug"
+    title: "并发保存偶发覆盖他人修改"
+    priority: "P1"
+    status: "leftover"
+    assignee: "developer"
+    component: "server/store/notes.go"
+    specRefs:
+      - "docs/spec/concurrency.md"
+    testRefs: []
+    description: >
+      两个会话同时保存同一条 note 时，后写覆盖先写，无冲突提示。
+    stepsToReproduce:
+      - "会话 A、B 同时打开 note 42"
+      - "A 保存，B 保存"
+    expected: >
+      B 保存时应检测到版本变化并提示冲突，而非静默覆盖。
+    actual: >
+      B 直接覆盖 A 的修改，无提示。
+    evidence:
+      api: "两次 PUT /api/notes/42 均返回 200，无版本校验"
+    verification:
+      commands:
+        - "go test ./server/store/..."
+      browser:
+        page: "/notes/42"
+        checks:
+          - "并发保存时后写方收到冲突提示"
+    dispatch:
+      taskId: "orca-task-90"
+      dispatchId: "orca-disp-95"
+      worker: "dev-worker-1"
+      rounds:
+        - round: 1
+          result: failed
+          evidence: "加了版本号但未在写入路径校验"
+        - round: 2
+          result: failed
+          evidence: "校验只覆盖 API，未覆盖批量导入路径"
+        - round: 3
+          result: failed
+          evidence: "乐观锁与前端重试逻辑冲突，需重新设计"
+    resolution:
+      fixedBy: null
+      verifiedAt: null
+      leftoverReason: "failed after 3 supervised developer rounds; 需重新设计并发模型"

kits/agent-collaboration-kit/optimization-method.md

@@ -1,194 +0,0 @@
-# Optimization Method
-
-本文件记录更稳的多 Agent 协作方法，目标是减少“开发声称完成但复测不过”的循环成本。
-
-## 1. 先把验收写成可观测信号
-
-不要只写“页面可用”“体验更好”。每个任务至少写三类信号：
-
-| 类型 | 示例 |
-|------|------|
-| 可见文本 | 页面出现 `确认应用标签`、`取消`、`将修改` |
-| API 结果 | `POST /api/...` 返回 `code=0` 且字段存在 |
-| 交互结果 | 点击按钮后出现确认区；取消后不触发写入 |
-
-好的验收：
-
-```text
-点击“预览变更”后，页面必须出现 API 返回的 diff 行：
-- title
-- 修改前值
-- 修改后值
-- coverChanged 提示
-```
-
-不好的验收：
-
-```text
-预览功能正常。
-```
-
-## 2. worker_done 必须带证据，不带结论
-
-Developer Worker 的 `worker_done` 应该报告：
-
-- 改了哪些文件。
-- 跑了哪些命令。
-- 自己如何复现验收路径。
-- 仍可能有的风险。
-
-不要让 Developer Worker 写：
-
-```text
-已完成，应该可以了。
-```
-
-要写：
-
-```text
-修改 web/app/fix/page.tsx。已运行 npm run build、go test ./...。
-手测 /fix?fileId=1：搜索、选择候选、预览、确认区都可见。
-风险：未执行真实写文件 apply。
-```
-
-## 3. Product/Test 只信自己的复测
-
-即使 worker_done 写了“全部通过”，Coordinator 仍必须重新：
-
-1. 确认 worktree。
-2. 构建或重启服务。
-3. 执行验收命令。
-4. 浏览器或 API 复测。
-5. 更新任务板。
-
-这可以避免三类假通过：
-
-- 测错服务实例。
-- 测到旧构建产物。
-- 开发只验证静态文本，没有验证真实交互。
-
-## 4. 三轮失败策略
-
-每个任务最多自动派发三轮。
-
-```text
-round 1: 常规修复
-round 2: 带复测失败证据的定向修复
-round 3: 明确指出重复失败点，要求 worker 自己复现完整路径
-failed after round 3: 标记 leftover，继续下一个任务
-```
-
-三轮失败后不要继续消耗同一个 worker。常见原因是：
-
-- 验收标准需要重新设计。
-- Worker 对问题模型理解错了。
-- UI 自动化与实际浏览器状态有差异。
-- 需要人工观察或调试工具介入。
-
-留档字段建议：
-
-```yaml
-status: leftover
-leftoverReason: "failed after 3 supervised developer rounds"
-attempts:
-  - round: 1
-    result: failed
-    evidence: "<why failed>"
-  - round: 2
-    result: failed
-    evidence: "<why failed>"
-  - round: 3
-    result: failed
-    evidence: "<why failed>"
-```
-
-## 5. 任务排序
-
-推荐排序：
-
-1. P0 阻塞主流程。
-2. P1 高频用户路径。
-3. P1/P2 体验改进。
-4. 重构和内部质量。
-
-三轮失败的 P0 可以留档，但最终发布前需要人工决策：
-
-- 降级范围。
-- 改验收标准。
-- 换新 Agent / 新 worktree 重做。
-- 人工修复。
-
-## 6. 每轮派发只修一个明确问题
-
-不要一次让 Developer Worker 修太多失败项，除非它们共享同一根因。推荐：
-
-```text
-one dispatch = one bug = one acceptance path
-```
-
-优点：
-
-- 复测更快。
-- 失败原因更清楚。
-- 三轮失败留档更准确。
-
-## 7. 复测前强制记录运行环境
-
-每轮复测前记录：
-
-```text
-repo:
-worktree:
-branch:
-commit:
-server command:
-BASE_URL:
-frontendDir:
-test commands:
-```
-
-如果服务是长跑进程，确认它加载的是最新构建产物。静态前端项目尤其要注意是否重新 `build`。
-
-## 8. 把失败证据写给下一轮 worker
-
-第二轮以后，派发 prompt 不应重复原始描述为主，而应突出“上一轮为什么没过”。
-
-模板：
-
-```text
-上一轮不是完全失败，以下部分已通过：
-- <passed checks>
-
-仍失败：
-- <missing checks>
-
-直接 API/底层验证：
-- <api result>
-
-请重点排查：
-- <suspected area>
-```
-
-## 9. 优先让测试可执行化
-
-如果某个问题需要多轮修复，说明它值得沉淀成自动化检查。优先级：
-
-1. API smoke。
-2. 浏览器脚本或 case 文档。
-3. 单元测试。
-4. 人工检查清单。
-
-目标不是所有东西都自动化，而是把最容易反复误判的路径自动化。
-
-## 10. 结束条件
-
-一轮闭环结束时，必须能回答：
-
-- 哪些任务 verified？
-- 哪些任务 leftover？
-- 每个 leftover 失败了几轮？
-- 最后一轮失败证据是什么？
-- 当前工作树有哪些未提交改动？
-- 是否还有 open / failed_retest 未处理？
-
-如果这些问题答不清楚，闭环还没有结束。

kits/agent-collaboration-kit/orca-closed-loop.md

@@ -1,229 +0,0 @@
-# Orca Closed Loop Workflow
-
-Orca orchestration 是运行时调度层，`tasks.yaml` 是持久事实源。不要把 Orca 消息当成最终记录；所有结论都要回写任务板。
-
-## 什么时候使用 Orca 编排
-
-使用：
-
-- 用户要求监督、等待结果、闭环修复、三轮重试。
-- 有多个 bug 或多个可独立派发的任务。
-- Product/Test 与 Developer 需要明确分工。
-- 需要 `worker_done` 后再复测。
-
-不使用：
-
-- 单次问答。
-- 用户只是要求完整 handoff，不需要你监督。
-- 不需要测试和复测的小改动。
-
-## 标准闭环
-
-```text
-Product/Test 发现或读取 open 任务
-  -> 写入/补全 tasks.yaml 验收标准
-  -> 创建 Orca task
-  -> dispatch 给 Developer Worker
-  -> 等待 worker_done / escalation / decision_gate
-  -> Product/Test 构建并复测
-  -> 通过：verified
-  -> 失败：failed_retest，追加证据，最多再派发两轮
-  -> 三轮失败：leftover，继续下一个任务
-```
-
-## 运行前检查
-
-```bash
-orca status --json
-orca terminal list --json
-orca orchestration task-list --json
-orca orchestration inbox --limit 20 --json
-```
-
-确认：
-
-- Orca runtime 可达。
-- Coordinator 终端和 Developer Worker 终端都存在。
-- Developer Worker 在正确 worktree。
-- 当前没有会冲突的活跃编排任务。
-
-## 创建父任务
-
-```bash
-orca orchestration task-create --spec "$(cat <<'EOF'
-Goal: Complete <release_or_feature> with supervised Product/Test -> Developer loop.
-
-Coordinator:
-- Owns task board, black-box tests, retest, final verification.
-
-Developer:
-- Owns implementation and white-box verification.
-
-Policy:
-- Each issue can be dispatched at most 3 rounds.
-- If still failing after 3 rounds, record as leftover and continue next issue.
-- worker_done is not final completion.
-EOF
-)" --json
-```
-
-## 创建子任务
-
-```bash
-orca orchestration task-create --parent <parent_task_id> --spec "$(cat <<'EOF'
-Fix <task_id>: <title>
-
-Repository:
-- Path: <repo_path>
-- Worktree: <dev_worktree>
-
-Read:
-- AGENTS.md
-- tasks.yaml
-- <relevant_spec_or_test_doc>
-
-Failure evidence:
-- <copy latest Product/Test evidence>
-
-Acceptance:
-- <copy expected behavior>
-- <copy verification commands>
-
-Constraints:
-- Follow AGENTS.md path scope.
-- Do not mark verified.
-- Do not commit or push unless user asks.
-EOF
-)" --json
-```
-
-## 派发给 Developer Worker
-
-如果终端是 Orca 可识别的 Agent CLI：
-
-```bash
-orca orchestration dispatch \
-  --task <task_id> \
-  --to <developer_handle> \
-  --inject \
-  --json
-```
-
-如果不能 `--inject`，先登记 dispatch，再手动发送带上下文的 prompt：
-
-```bash
-orca orchestration dispatch \
-  --task <task_id> \
-  --to <developer_handle> \
-  --json
-```
-
-```bash
-orca terminal send --terminal <developer_handle> --text "$(cat <<'EOF'
-You are receiving a supervised Orca task.
-
-taskId: <task_id>
-dispatchId: <dispatch_id>
-coordinator: <coordinator_handle>
-
-Task:
-- Fix <task_id>: <title>
-
-Acceptance:
-- <expected behavior>
-
-Verification:
-- <test_commands>
-
-When done, send exactly one worker_done:
-orca orchestration send --to <coordinator_handle> --type worker_done --subject "<task_id> fixed" --body "<summary>" --payload '{"taskId":"<task_id>","dispatchId":"<dispatch_id>","filesModified":["<paths>"],"verification":["<commands>"]}' --json
-EOF
-)" --enter --json
-```
-
-## 等待结果
-
-```bash
-orca orchestration check \
-  --terminal <coordinator_handle> \
-  --wait \
-  --types worker_done,escalation,decision_gate \
-  --timeout-ms 900000 \
-  --json
-```
-
-等待超时不等于失败。长任务可以继续等待，或检查 worker 终端活性。
-
-## worker_done 后复测
-
-Product/Test 必须自己验证：
-
-```bash
-git status --short
-<test_commands>
-curl -s <base_url>/health-or-summary
-```
-
-浏览器复测建议记录：
-
-```text
-BASE_URL:
-page:
-steps:
-expected:
-actual:
-snapshot evidence:
-```
-
-## 服务与 worktree 对齐
-
-复测前记录：
-
-```bash
-pwd
-git rev-parse --abbrev-ref HEAD
-git rev-parse --short HEAD
-```
-
-记录服务：
-
-```text
-serverPid:
-serverCommand:
-BASE_URL:
-frontendDir:
-worktreePath:
-```
-
-如果开发在 `<dev_worktree>` 修复，但服务跑的是另一个 worktree，必须停止并重启正确服务后再测。
-
-## 结果回写
-
-通过：
-
-```yaml
-status: verified
-verifiedAt: "<timestamp>"
-evidence:
-  verification: "<commands passed>"
-  browser: "<snapshot or API evidence>"
-```
-
-失败但未满三轮：
-
-```yaml
-status: failed_retest
-attempts:
-  - round: 1
-    result: failed
-    evidence: "<latest evidence>"
-```
-
-三轮失败：
-
-```yaml
-status: leftover
-leftoverReason: "failed after 3 supervised developer rounds"
-evidence:
-  final: "<latest failing evidence>"
-```

kits/agent-collaboration-kit/prompt-templates.md

@@ -1,137 +0,0 @@
-# Prompt Templates
-
-这些模板用于 Coordinator 给 Developer Worker 派发任务。复制时替换尖括号占位符。
-
-## 1. 初始派发模板
-
-```text
-你现在接到一个受监督的 Orca 编排任务。请在 <dev_worktree> 开发工作树内完成。
-
-编排上下文：
-- taskId: <orca_task_id>
-- dispatchId: <orca_dispatch_id>
-- coordinator: <coordinator_handle>
-
-任务：
-- 修复 <task_id>: <task_title>
-
-请先读取：
-- AGENTS.md
-- tasks.yaml
-- <relevant_spec_or_test_doc>
-
-当前失败证据：
-<copy latest Product/Test evidence>
-
-验收标准：
-1. <expected behavior 1>
-2. <expected behavior 2>
-3. <expected behavior 3>
-
-约束：
-- 只修改 Developer 可写路径。
-- 不要修改 Product/Test 负责的规格和集成测试文件，除非任务明确要求。
-- 不要标记 verified。
-- 不要提交或推送，除非用户明确要求。
-- 最小 diff，避免无关重构。
-
-完成前必须运行：
-- <test command 1>
-- <test command 2>
-- <test command 3>
-
-完成后发送一次 worker_done：
-orca orchestration send --to <coordinator_handle> --type worker_done --subject "<task_id> fix ready round <n>" --body "<三句话内：修了什么、验证、风险>" --payload '{"taskId":"<orca_task_id>","dispatchId":"<orca_dispatch_id>","filesModified":["<paths>"],"verification":["<commands>"]}' --json
-
-如果阻塞，请发送 escalation 或 ask。
-```
-
-## 2. 复测失败再派发模板
-
-```text
-第 <n> 轮 QA 未通过，请继续修 <task_id>。
-
-上一轮开发声称：
-<worker_done summary>
-
-Product/Test 独立复测结果：
-- 运行命令：<commands>
-- 失败页面/API：<page or endpoint>
-- 仍缺失：<missing expected checks>
-- 实际观察：<actual evidence>
-
-关键提示：
-- 不要只满足静态文案，必须满足交互后的真实状态。
-- 如果后端/API 正常而 UI 不更新，请优先排查事件链、状态重置、异步请求、构建产物和服务 worktree。
-- 修复后请自己用浏览器或脚本复现 Product/Test 的完整步骤。
-
-验收不变：
-<copy acceptance criteria>
-
-完成后发送 worker_done，subject 使用：
-"<task_id> fix ready round <n>"
-```
-
-## 3. 三轮失败留档模板
-
-```text
-<task_id> 已完成 3 轮受监督修复，但仍未通过 Product/Test 复测。
-
-最终状态：
-- status: leftover
-- reason: failed after 3 supervised developer rounds
-
-保留证据：
-- round 1: <summary>
-- round 2: <summary>
-- round 3: <summary>
-- final failing evidence: <latest evidence>
-
-处理策略：
-- 不再自动派发同一问题。
-- 继续处理下一个 open / failed_retest 任务。
-- 该问题留给人工专项检查或后续重新设计。
-```
-
-## 4. Developer Worker worker_done 模板
-
-```bash
-orca orchestration send \
-  --to <coordinator_handle> \
-  --type worker_done \
-  --subject "<task_id> fix ready round <n>" \
-  --body "<修了什么。跑了哪些验证。还有什么风险。>" \
-  --payload '{
-    "taskId": "<orca_task_id>",
-    "dispatchId": "<orca_dispatch_id>",
-    "filesModified": [
-      "<file_a>",
-      "<file_b>"
-    ],
-    "verification": [
-      "<command_a>: passed",
-      "<command_b>: passed"
-    ],
-    "risk": "<remaining risk or none>"
-  }' \
-  --json
-```
-
-## 5. Coordinator 最终报告模板
-
-```text
-本轮闭环完成。
-
-已验证：
-- <task_id>: <what passed>
-
-遗留：
-- <task_id>: 三轮仍未通过，已记录为 leftover。最后失败证据：<evidence>
-
-验证命令：
-- <command>: passed
-
-工作树状态：
-- <repo_path>: <git status summary>
-- <dev_worktree>: <git status summary>
-```

kits/agent-collaboration-kit/scripts/validate_tasks.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""校验 tasks.yaml 是否符合 agent-collaboration-kit 任务板结构。
+
+权威结构是同目录上层的 templates/tasks.schema.json（跨语言可用）。
+本脚本是参考实现：
+  - 若安装了 jsonschema，则用 schema 做完整校验；
+  - 否则回退到内置的关键规则校验（必填字段、状态枚举、三轮上限、leftover 留档）。
+YAML 解析优先用 pyyaml；未安装时给出提示而非崩溃。
+
+用法:
+    python3 validate_tasks.py [tasks.yaml]
+    python3 validate_tasks.py --schema path/to/tasks.schema.json tasks.yaml
+
+退出码: 0 通过 / 1 校验失败 / 2 环境或用法错误。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+STATUS_ENUM = {
+    "open",
+    "dispatched",
+    "fixed_by_dev",
+    "retesting",
+    "failed_retest",
+    "verified",
+    "blocked",
+    "leftover",
+}
+MAX_ROUNDS = 3
+
+
+def load_yaml(path: Path) -> dict:
+    try:
+        import yaml  # type: ignore
+    except ImportError:
+        sys.stderr.write(
+            "需要 PyYAML 才能解析 YAML：pip install pyyaml\n"
+            "（或把任务板导出为 JSON 后再校验）\n"
+        )
+        raise SystemExit(2)
+    try:
+        with path.open(encoding="utf-8") as fh:
+            data = yaml.safe_load(fh)
+    except yaml.YAMLError as exc:  # type: ignore
+        sys.stderr.write(f"YAML 解析失败: {exc}\n")
+        raise SystemExit(1)
+    if not isinstance(data, dict):
+        sys.stderr.write("任务板顶层必须是对象（mapping）\n")
+        raise SystemExit(1)
+    return data
+
+
+def validate_with_schema(data: dict, schema_path: Path) -> list[str]:
+    import jsonschema  # type: ignore
+
+    schema = json.loads(schema_path.read_text(encoding="utf-8"))
+    validator = jsonschema.Draft7Validator(schema)
+    errors = []
+    for err in sorted(validator.iter_errors(data), key=lambda e: list(e.path)):
+        loc = "/".join(str(p) for p in err.path) or "<root>"
+        errors.append(f"[schema] {loc}: {err.message}")
+    return errors
+
+
+def validate_builtin(data: dict) -> list[str]:
+    errors: list[str] = []
+
+    if not isinstance(data.get("version"), int) or data.get("version", 0) < 1:
+        errors.append("version 必须是 >=1 的整数")
+    project = data.get("project")
+    if not isinstance(project, dict) or not project.get("name"):
+        errors.append("project.name 必填")
+
+    tasks = data.get("tasks")
+    if not isinstance(tasks, list):
+        errors.append("tasks 必须是列表")
+        return errors
+
+    seen_ids: set[str] = set()
+    for i, task in enumerate(tasks):
+        where = f"tasks[{i}]"
+        if not isinstance(task, dict):
+            errors.append(f"{where}: 必须是对象")
+            continue
+        tid = task.get("id")
+        title = task.get("title")
+        status = task.get("status")
+        if not tid:
+            errors.append(f"{where}: id 必填")
+        else:
+            where = f"tasks[{i}] {tid}"
+            if tid in seen_ids:
+                errors.append(f"{where}: id 重复")
+            seen_ids.add(tid)
+        if not title:
+            errors.append(f"{where}: title 必填")
+        if status not in STATUS_ENUM:
+            errors.append(
+                f"{where}: status={status!r} 非法，应为 {sorted(STATUS_ENUM)}"
+            )
+
+        dispatch = task.get("dispatch") or {}
+        rounds = dispatch.get("rounds") or []
+        if isinstance(rounds, list):
+            if len(rounds) > MAX_ROUNDS:
+                errors.append(
+                    f"{where}: 派发轮次 {len(rounds)} 超过上限 {MAX_ROUNDS}"
+                )
+            for r in rounds:
+                if isinstance(r, dict) and r.get("result") not in {"passed", "failed"}:
+                    errors.append(f"{where}: round.result 必须是 passed/failed")
+
+        if status == "leftover":
+            resolution = task.get("resolution") or {}
+            if not resolution.get("leftoverReason"):
+                errors.append(f"{where}: leftover 必须填 resolution.leftoverReason")
+
+    return errors
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="校验 tasks.yaml 结构")
+    parser.add_argument("tasks", nargs="?", default="tasks.yaml", help="任务板路径")
+    parser.add_argument("--schema", help="tasks.schema.json 路径（默认自动探测）")
+    args = parser.parse_args(argv)
+
+    tasks_path = Path(args.tasks)
+    if not tasks_path.is_file():
+        sys.stderr.write(f"找不到任务板文件: {tasks_path}\n")
+        return 2
+
+    data = load_yaml(tasks_path)
+
+    schema_path = Path(args.schema) if args.schema else (
+        Path(__file__).resolve().parent.parent / "templates" / "tasks.schema.json"
+    )
+
+    mode = "内置规则"
+    try:
+        import jsonschema  # type: ignore  # noqa: F401
+
+        if schema_path.is_file():
+            errors = validate_with_schema(data, schema_path)
+            mode = f"schema ({schema_path.name})"
+        else:
+            errors = validate_builtin(data)
+            mode = "内置规则（未找到 schema 文件）"
+    except ImportError:
+        errors = validate_builtin(data)
+
+    if errors:
+        sys.stderr.write(f"任务板校验失败（{mode}），共 {len(errors)} 项：\n")
+        for e in errors:
+            sys.stderr.write(f"  - {e}\n")
+        return 1
+
+    sys.stdout.write(f"任务板校验通过（{mode}）：{tasks_path}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

kits/agent-collaboration-kit/templates/AGENTS.template.md

@@ -0,0 +1,64 @@
+# <项目名> Agent 协作协议
+
+> 本项目基于 agent-collaboration-kit v<kit_version>（见 kit 根 `VERSION`）。
+> 稳定规范引用 `docs/agent-collaboration-kit/core/`，不复制其内容；本文件只填项目自己的差异。
+
+## 项目概览
+
+- 项目：`<project_name>`
+- 技术栈：`<tech_stack>`
+- 运行命令：`<run_command>`
+- Base URL：`<base_url>`
+- 任务板：`tasks.yaml`
+
+## 稳定规范（不在此重复，直接引用）
+
+- 角色模型 / 权限 / 状态机 / 完成定义：`docs/agent-collaboration-kit/core/roles-and-permissions.md`
+- 闭环流程（含手动模式、worktree 对齐）：`docs/agent-collaboration-kit/core/closed-loop.md`
+- 优化方法（验收信号、三轮策略）：`docs/agent-collaboration-kit/core/optimization-method.md`
+- 派发 prompt 模板：`docs/agent-collaboration-kit/core/prompt-templates.md`
+- Orca 编排命令（可选）：`docs/agent-collaboration-kit/core/orca-adapter.md`
+
+## 路径权限（项目覆盖层，必须填实际路径）
+
+| 路径 | Product/Test | Developer | 说明 |
+|------|:------------:|:---------:|------|
+| `<spec_paths>` | R/W | Read-only | 产品规格、API 文档、计划 |
+| `<integration_test_paths>` | R/W | Read-only | 浏览器/API 回归 |
+| `<test_records_path>` | R/W | Read-only | 复测记录 |
+| `<source_paths>` | Read-only | R/W | 应用源码 |
+| `<unit_test_paths>` | Read-only | R/W | 单元测试 |
+| `<shared_config_templates>` | Read-only | R/W | 可提交配置模板 |
+| `<local_config_paths>` | Read-only | Read-only | 本地私有配置 |
+| `tasks.yaml` | R/W | Read-only | 只有 Coordinator 写 |
+
+## 命令（项目覆盖层）
+
+Developer 白盒验证：
+
+```bash
+<unit_test_command>
+<build_command>
+<local_run_command>
+```
+
+Product/Test 黑盒验证：
+
+```bash
+<preflight_command>
+<api_smoke_command>
+<browser_regression_command>
+```
+
+任务板校验：
+
+```bash
+python3 docs/agent-collaboration-kit/scripts/validate_tasks.py tasks.yaml
+```
+
+## 硬规则（其余见 core/）
+
+- `worker_done` 不等于完成。Product/Test 必须独立复测后才能 `verified`。
+- 只有 Coordinator 写 `tasks.yaml`；Developer 通过 worker_done 回报。
+- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续下一个。
+- 不提交或推送，除非用户明确要求。

kits/agent-collaboration-kit/templates/tasks.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://git.yumee.top/laily/skills/kits/agent-collaboration-kit/tasks.schema.json",
+  "title": "Agent Collaboration Kit task board",
+  "description": "tasks.yaml 的权威结构。跨语言可用；参考校验实现见 scripts/validate_tasks.py。",
+  "type": "object",
+  "required": ["version", "project", "tasks"],
+  "additionalProperties": true,
+  "properties": {
+    "version": { "type": "integer", "minimum": 1 },
+    "updatedAt": { "type": "string" },
+    "source": { "type": "string" },
+    "kitVersion": {
+      "type": "string",
+      "description": "接入时所基于的 agent-collaboration-kit 版本，便于日后 diff 升级"
+    },
+    "project": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string" },
+        "repoPath": { "type": "string" },
+        "baseUrl": { "type": "string" },
+        "devWorktree": { "type": "string" }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "verified": { "type": "array", "items": { "type": "string" } },
+        "open": { "type": "array", "items": { "type": "string" } },
+        "failedRetest": { "type": "array", "items": { "type": "string" } },
+        "leftovers": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "statusReference": { "type": "object" },
+    "tasks": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/task" }
+    }
+  },
+  "definitions": {
+    "status": {
+      "type": "string",
+      "enum": [
+        "open",
+        "dispatched",
+        "fixed_by_dev",
+        "retesting",
+        "failed_retest",
+        "verified",
+        "blocked",
+        "leftover"
+      ]
+    },
+    "round": {
+      "type": "object",
+      "required": ["round", "result"],
+      "additionalProperties": true,
+      "properties": {
+        "round": { "type": "integer", "minimum": 1 },
+        "result": { "type": "string", "enum": ["passed", "failed"] },
+        "evidence": { "type": "string" }
+      }
+    },
+    "task": {
+      "type": "object",
+      "required": ["id", "title", "status"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "type": { "type": "string" },
+        "title": { "type": "string", "minLength": 1 },
+        "priority": { "type": "string" },
+        "status": { "$ref": "#/definitions/status" },
+        "assignee": { "type": "string" },
+        "component": { "type": "string" },
+        "specRefs": { "type": "array", "items": { "type": "string" } },
+        "testRefs": { "type": "array", "items": { "type": "string" } },
+        "description": { "type": "string" },
+        "stepsToReproduce": { "type": "array", "items": { "type": "string" } },
+        "expected": { "type": "string" },
+        "actual": { "type": "string" },
+        "evidence": { "type": "object" },
+        "verification": { "type": "object" },
+        "dispatch": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "taskId": { "type": ["string", "null"] },
+            "dispatchId": { "type": ["string", "null"] },
+            "worker": { "type": ["string", "null"] },
+            "rounds": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/round" }
+            }
+          }
+        },
+        "resolution": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "fixedBy": { "type": ["string", "null"] },
+            "verifiedAt": { "type": ["string", "null"] },
+            "leftoverReason": { "type": ["string", "null"] },
+            "evidence": { "type": "object" }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "status": { "const": "leftover" } } },
+          "then": {
+            "properties": {
+              "resolution": {
+                "required": ["leftoverReason"]
+              }
+            },
+            "required": ["resolution"]
+          }
+        }
+      ]
+    }
+  }
+}

kits/agent-collaboration-kit/templates/tasks.template.yaml

@@ -1,6 +1,8 @@
+# 复制到项目根目录为 tasks.yaml，替换占位符。结构见 templates/tasks.schema.json。
 version: 1
 updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
 source: "Product/Test Agent"
+kitVersion: "<接入时的 agent-collaboration-kit 版本，见 kit 根 VERSION>"
 project:
   name: "<project_name>"
   repoPath: "<repo_path>"
@@ -32,7 +34,6 @@ tasks:
     stepsToReproduce:
       - "<step 1>"
       - "<step 2>"
-      - "<step 3>"
 
     expected: >
       <Expected behavior.>
@@ -64,13 +65,3 @@ tasks:
       fixedBy: null
       verifiedAt: null
       leftoverReason: null
-
-statusReference:
-  open: "Product/Test found issue; not dispatched yet"
-  dispatched: "Sent to Developer Worker"
-  fixed_by_dev: "Developer claims fixed and provides verification"
-  retesting: "Product/Test is verifying"
-  failed_retest: "Product/Test verification failed"
-  verified: "Product/Test verification passed"
-  blocked: "Needs user or external decision"
-  leftover: "Failed after 3 developer rounds; preserved for later manual review"