feat:

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

@@ -6,30 +6,35 @@
 
 ---
 
-## 角色模型
+## 角色模型（三角色）
+
+本 kit 默认三个独立 Agent：**Coordinator 只编排、Test 只验证、Developer 只实现**。关键属性是**验证者 ≠ 实现者**：Developer 不能给自己盖章，验证权在独立的 Test。
 
 | 角色 | 主要职责 | 验证方式 | 不应做的事 |
 |------|----------|----------|------------|
-| Product/Test Coordinator | 需求拆解、任务记录、黑盒测试、复测验收、调度开发 | 浏览器、API、集成脚本、用户可见行为 | 修改应用源码、凭 worker_done 直接标记完成 |
-| Developer Worker | 实现修复、写单元测试、运行构建和白盒验证 | 单元测试、类型检查、构建、本地运行 | 修改产品规格、标记 verified、绕过测试声称完成 |
+| Coordinator (PM) | 需求拆解、定验收信号、排优先级、写 `tasks.yaml`、向 Developer/Test 派发、跑三轮闭环、做最终 gate | 读 Test 证据并对齐原始意图（不亲自跑测试） | 修改源码、亲自复测、凭 worker_done 直接标 `verified` |
+| Test | 黑盒复测、回归验证、沉淀可执行测试、产出证据 | 浏览器、API、集成脚本、用户可见行为 | 修改应用源码、修改产品规格、写 `tasks.yaml` |
+| Developer | 实现修复、写单元测试、运行构建和白盒验证 | 单元测试、类型检查、构建、本地运行 | 修改产品规格与集成测试、标记 `verified`、绕过测试声称完成 |
 | User / Decision Owner | 决定范围、优先级、阻塞项是否继续 | 审阅报告和遗留清单 | 直接替代复测证据 |
 
+**独立验证权归 Test。** Coordinator 不亲自复测——它读 Test 的证据，并对照任务的原始意图做一次终检（见「完成定义」）。`worker_done` 不等于完成的原则同时适用于 Developer 和 Test：结论只有落到 `tasks.yaml` 才算数。
+
 ---
 
 ## 路径权限模板
 
 目标项目在自己的 `AGENTS.md` 中填入实际路径（见 `templates/AGENTS.template.md`）。
 
-| 路径 | Product/Test | Developer | 说明 |
-|------|:------------:|:---------:|------|
-| `<spec_paths>` | R/W | Read-only | PRD、API spec、设计文档 |
-| `<integration_test_paths>` | R/W | Read-only | 浏览器用例、API smoke、回归清单 |
-| `<test_records_path>` | R/W | Read-only | 复测记录，通常可 gitignore |
-| `<source_paths>` | Read-only | R/W | 应用源码 |
-| `<unit_test_paths>` | Read-only | R/W | 单元测试 |
-| `<shared_config_templates>` | Read-only | R/W | 可提交配置模板 |
-| `<local_config>` | Read-only | Read-only | 本地私有配置，不提交 |
-| `tasks.yaml` | R/W | Read-only | 见下方「任务板写入约定」 |
+| 路径 | Coordinator | Test | Developer | 说明 |
+|------|:-----------:|:----:|:---------:|------|
+| `<spec_paths>` | R/W | Read-only | Read-only | PRD、API spec、设计文档，Coordinator（PM）拥有 |
+| `<integration_test_paths>` | Read-only | R/W | Read-only | 浏览器用例、API smoke、回归清单，Test 拥有 |
+| `<test_records_path>` | Read-only | R/W | Read-only | 复测记录，通常可 gitignore |
+| `<source_paths>` | Read-only | Read-only | R/W | 应用源码 |
+| `<unit_test_paths>` | Read-only | Read-only | R/W | 单元测试 |
+| `<shared_config_templates>` | Read-only | Read-only | R/W | 可提交配置模板 |
+| `<local_config>` | Read-only | Read-only | Read-only | 本地私有配置，不提交 |
+| `tasks.yaml` | R/W | Read-only | Read-only | 见下方「任务板写入约定」 |
 
 ---
 
@@ -37,32 +42,32 @@
 
 ```text
 open
-  -> dispatched
-  -> fixed_by_dev
-  -> retesting
-  -> verified
+  -> dispatched      （派发给 Developer）
+  -> fixed_by_dev    （Developer 声称已修）
+  -> retesting       （派发给 Test 复测）
+  -> verified        （Test 通过 + Coordinator 终检）
 ```
 
 失败分支：
 
 ```text
 dispatched     -> blocked
-fixed_by_dev   -> failed_retest -> dispatched
+retesting      -> failed_retest -> dispatched
 failed_retest（累计 3 轮） -> leftover
 ```
 
-状态定义：
+状态定义（所有状态都只由 Coordinator 写入 `tasks.yaml`，来源不同）：
 
-| 状态 | 写入者 | 含义 |
-|------|--------|------|
-| `open` | Product/Test | 已发现，等待处理 |
-| `dispatched` | Product/Test | 已派发给开发 Agent |
-| `fixed_by_dev` | Product/Test（据 worker_done 回写） | 开发声称已修复并提供验证 |
-| `retesting` | Product/Test | 正在复测 |
-| `failed_retest` | Product/Test | 复测失败，可继续派发 |
-| `verified` | Product/Test | 复测通过 |
-| `blocked` | Product/Test | 需要用户决策或外部条件 |
-| `leftover` | Product/Test | 累计 3 轮仍未通过，留给人工或专项处理 |
+| 状态 | 依据来源 | 含义 |
+|------|----------|------|
+| `open` | Coordinator 自己发现/记录 | 已发现，等待处理 |
+| `dispatched` | Coordinator 派发动作 | 已派发给 Developer |
+| `fixed_by_dev` | Developer 的 worker_done | 开发声称已修复并提供白盒验证 |
+| `retesting` | Coordinator 派发动作 | 已派发给 Test，正在黑盒复测 |
+| `failed_retest` | Test 的复测报告 | 复测失败，可继续派发 Developer |
+| `verified` | Test 通过 + Coordinator 终检 | 复测通过且符合原始意图 |
+| `blocked` | Coordinator 判断 | 需要用户决策或外部条件 |
+| `leftover` | Coordinator 判断 | 累计 3 轮仍未通过，留给人工或专项处理 |
 
 三轮失败的处理细则见 `optimization-method.md` §「三轮失败策略」。
 
@@ -70,10 +75,10 @@ failed_retest（累计 3 轮） -> leftover
 
 ## 任务板写入约定（并发安全）
 
-`tasks.yaml` 是持久事实源，为避免多 Worker 并发写冲突：
+`tasks.yaml` 是持久事实源，为避免多 Agent 并发写冲突：
 
-- **只有 Coordinator 写 `tasks.yaml`**。Developer Worker 对它是只读的。
-- Developer 的实现状态、证据通过 `worker_done` 消息回传，由 Coordinator 落盘。
+- **只有 Coordinator 写 `tasks.yaml`**。Test 与 Developer 对它都是只读的。
+- Developer 的实现状态、Test 的复测证据都通过消息回传（`worker_done` / 复测报告），由 Coordinator 落盘。
 - 每次写入前先读最新内容，写入后更新顶层 `updatedAt`。
 - 单次写入应是一个任务的一次状态跃迁，避免整表批量重写。
 
@@ -83,8 +88,9 @@ failed_retest（累计 3 轮） -> leftover
 
 一个任务只有同时满足以下条件，才能标记 `verified`：
 
-- Developer 已提供修改文件和验证证据。
-- Product/Test 在正确 worktree 和正确服务实例上复测（对齐检查见 `closed-loop.md`）。
+- Developer 已提供修改文件和白盒验证证据（`worker_done`）。
+- Test 在正确 worktree 和正确服务实例上独立复测通过（对齐检查见 `closed-loop.md`），并产出可观测证据。
 - 相关单元测试、构建、集成或浏览器检查通过。
-- `tasks.yaml` 中记录了复测证据。
+- **Coordinator 终检**：读 Test 的证据，确认它满足任务的原始意图与验收信号（不是重测，是审证据 + 对齐意图；避免"过了字面没过意图"）。
+- `tasks.yaml` 中记录了复测证据与 `resolution.verifiedBy`。
 - 用户可见行为符合验收标准。