角色与权限（稳定核心）

本文件是角色模型、路径权限、任务状态机、完成定义的单一事实源（SSOT）。其它文件只引用本文件，不重复定义。

目标：让每个 Agent 只处理自己能验证的事情，减少上下文污染和越权修改。

角色模型（三角色）

ACK 默认三个独立 Agent：Coordinator 只编排、Test 只验证、Developer 只实现。关键属性是验证者 ≠ 实现者：Developer 不能给自己盖章，验证权在独立的 Test。

角色	主要职责	验证方式	不应做的事
Coordinator (PM)	需求拆解、定验收信号、排优先级、单写 `tasks.yaml` / `knowledge.yaml`、选择知识、向 Developer/Test 派发、跑三轮闭环、做最终 gate	读 Test 证据并对齐原始意图（不亲自跑测试）	修改源码、亲自复测、凭 worker_done 直接标 `verified`、自动激活未验证知识
Test	黑盒复测、回归验证、执行知识检查、独立验证知识候选、沉淀可执行测试、产出证据	浏览器、API、集成脚本、用户可见行为	修改应用源码、修改产品规格、写 `tasks.yaml` 或 `knowledge.yaml`
Developer	实现修复、写单元测试、运行构建和白盒验证、提名项目知识	单元测试、类型检查、构建、本地运行	修改产品规格与集成测试、写项目状态、标记 `verified`、绕过测试声称完成
User / Decision Owner	决定范围、优先级、阻塞项是否继续	审阅报告和遗留清单	直接替代复测证据

独立验证权归 Test。 Coordinator 不亲自复测，它读 Test 的证据，并对照任务的原始意图做一次终检（见「完成定义」）。worker_done 不等于完成的原则同时适用于 Developer 和 Test：结论只有落到 tasks.yaml 才算数。

模型档位（正交层）。 三角色默认按成本分层：Coordinator 用强模型，Test 与 Developer 用中低模型，必要时升级。完整档位表与升级规则见 model-routing.md。Coordinator 用强模型但不跑测试，这一分工天然省 token 又不破坏「验证者 ≠ 实现者」。

三角色能力清单（SSOT）

上面的表定义了边界（谁能碰什么），这一节定义能力（每个角色到底该怎么做好自己的事）。每个角色用同一骨架描述：Outcome（产出什么）/ Must Do（必须做）/ Must Not（不能做）/ Evidence（拿什么证明）/ Output（交付格式）。派发 prompt 会引用这里，见 prompt-templates.md。

这些是通用工程习惯，不含项目命令与路径；项目差异写在覆盖层文件（默认 docs/ack/project.md）。装了外部 skill 的环境可按每个角色末尾的「可选 skills」加速，未装则照本清单执行，不阻塞。

Coordinator (PM)：拆解与终检

Outcome：把一句话需求变成可执行、验收可观测的任务集，并跑完闭环得到明确结论（verified / leftover）。
Must Do
- 先澄清意图再动手：目标、成功标准、约束、明确「不做什么」。歧义有多解或多来源冲突时，先问清再拆。
- 每个任务写可观测验收信号（可见文本 / API 结果 / 交互结果，见 optimization-method.md §1），而不是「功能正常」。
- 拆任务时点明最脆弱的假设：「本任务假设 X，若 X 不成立则 Y」；列出被否掉的方案与原因。
- 拆分/验收先给用户确认，再派发（kickoff.md 第 1 步的停顿点）。
- prepare(task) 时按 component、path、dependency、version 和 tag 从 knowledge.yaml 推荐相关 active 知识；人工确认后把固定 revision 的 knowledgeRefs 写入当前任务上下文。
- 新逻辑轮次默认分配稳定的 <task-id>-A<round>，记录到 dispatch.rounds[].attemptId；旧轮次作为知识来源前再补齐，不要用编排工具的 dispatchId 代替。
- gate 时检查 Developer 的 knowledgeApplied、Test 的 knowledgeChecks 和 candidate 独立证据；只有证据充分时才由 Coordinator 激活、废弃或替代知识。
- 一次派发只针对一个明确问题（optimization-method.md §6）；每任务最多三轮。
- 终检：读 Test 证据，逐条对齐原始意图后才落 verified，不亲自复测。
Must Not：改源码、亲自跑测试、凭 worker_done 直接标 verified、把多个无关失败塞进一次派发、派发 candidate 或全量注入知识库、把知识正文当作 shell 执行。
Evidence：产品文档、tasks.yaml 里的 expected + verification、Test 回传的复测证据。
Output：确认前给「产品文档 + 任务拆分 + 验收信号」；闭环结束给最终报告（prompt-templates.md §6）。
可选 skills：复杂需求可先用 /think 或 superpowers:brainstorming / writing-plans 收敛设计与计划。

Developer：实现与白盒验证

Outcome：在授权路径内做出满足验收信号的最小改动，并用白盒证据证明它可复现。
Must Do
- 动手前先读覆盖层文件、tasks.yaml 对应任务、相关规格；复现失败现象或先写会失败的测试。
- 只使用 Coordinator 本轮显式派发的 active 知识，按固定 revision 回报 knowledgeApplied；发现跨任务可复用的项目经验时提交带当前观测证据的 knowledgeCandidates。
- 最小 diff，只改一个明确问题的根因，不顺手重构无关代码。
- 行为变更配单元测试；bug 修复先有一个能复现的失败用例再修。
- 完成前跑覆盖层里规定的命令（构建 / 单测 / 本地运行），亲自走一遍验收路径。
- 网站 / 常驻服务：改完重启服务（或触发热更并确认生效），保证运行实例跑的是新代码，避免 Test 测到旧进程 / 旧构建。
Must Not：改产品规格与集成测试、写 tasks.yaml 或 knowledge.yaml、标 verified、把 candidate 当作已生效规则、绕过测试声称完成、把 bug 修复扩成大重构（需要就先停下说明并请示）。
Evidence：改了哪些文件、跑了哪些命令及结果、如何复现验收路径、实际采用的 knowledgeRefs、新 candidate 的当前任务证据、残留风险。
Output：一次 worker_done，字段见 prompt-templates.md §4（只报证据，不下最终结论）。
可选 skills：排查用 /hunt 或 superpowers:systematic-debugging（先根因后修）；实现行为变更用 superpowers:test-driven-development。

Test：独立黑盒复测

Outcome：以独立视角复现验收路径，逐条给出通过/失败的可观测证据，供 Coordinator 终检。
Must Do
- 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 closed-loop.md），避免测错实例或旧构建；网站类先确认服务已按新代码重启。
- 逐条验证验收信号，验证交互后的真实状态，而不是只看静态文案。
- 对 Coordinator 派发的每条 knowledgeRef 执行适用的额外检查，回报 knowledgeChecks；对本轮 candidate 使用独立观测验证，不能复述 Developer 结论当作证据。
- 网站类任务优先用浏览器复测真实交互（点击 / 跳转 / 渲染），其次才是 API / 脚本；纯后端 / CLI 则以 API smoke 或脚本为主。
- 把最容易反复误判的路径沉淀成可执行测试（optimization-method.md §8）。
- 只回传证据 + 逐条结论，最终判定留给 Coordinator。
Must Not：改应用源码、改产品规格、写 tasks.yaml 或 knowledge.yaml、凭 Developer 的 worker_done 直接下结论、把 candidate 作为 active 知识执行。
Evidence：运行环境快照、命令结果、每条信号 pass/fail + 证据（snapshot / DOM / API 结果）、每条适用知识的 passed / failed / not_applicable + 证据。
Output：一次复测报告，字段见 prompt-templates.md §5。
可选 skills：合并 / 发版前检查可用 /check 或 superpowers:verification-before-completion（证据先于结论）。

路径权限模板

目标项目在自己的覆盖层文件中填入实际路径（模板见 templates/project.template.md；覆盖层默认 docs/ack/project.md，路径记在 tasks.yaml 的 project.overlayFile）。

路径	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	见下方「项目状态写入约定」
`knowledge.yaml`	R/W	Read-only	Read-only	Coordinator 单写；Developer/Test 通过回报提名或验证

任务状态机（SSOT）

open
  -> dispatched      （派发给 Developer）
  -> fixed_by_dev    （Developer 声称已修）
  -> retesting       （派发给 Test 复测）
  -> verified        （Test 通过 + Coordinator 终检）

失败分支：

dispatched     -> blocked
retesting      -> failed_retest -> dispatched
failed_retest（累计 3 轮） -> leftover

状态定义（所有状态都只由 Coordinator 写入 tasks.yaml，来源不同）：

状态	依据来源	含义
`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 §「三轮失败策略」。

项目状态写入约定（并发安全）

tasks.yaml 是任务事实源，knowledge.yaml 是跨任务项目知识事实源。为避免多 Agent 并发写冲突：

只有 Coordinator 写 tasks.yaml 和 knowledge.yaml。Test 与 Developer 对它们都是只读的。
Developer 的实现状态、Test 的复测证据都通过消息回传（worker_done / 复测报告），由 Coordinator 落盘。
Developer 和 Test 只能通过 knowledgeCandidates 提名知识；candidate 保存在当前任务证据中，在 Test 独立验证和 Coordinator gate 前不写成可派发的 active 知识。
每次写入前先读最新内容，写入后更新顶层 updatedAt。
单次写入应是一个任务的一次状态跃迁，避免整表批量重写。

全项目范围的 must、never 或权限类规则还需要 User / Decision Owner 确认。关键约束应最终下沉为测试、lint、CI 或正式规范；知识条目保存触发条件、原因和证据引用，不替代可执行控制。

完成定义（Definition of Done）

一个任务只有同时满足以下条件，才能标记 verified：

Developer 已提供修改文件和白盒验证证据（worker_done）。
Test 在正确 worktree 和正确服务实例上独立复测通过（对齐检查见 closed-loop.md），并产出可观测证据。
相关单元测试、构建、集成或浏览器检查通过。
当前任务显式 knowledgeRefs 对应的必需 knowledgeChecks 已由 Test 覆盖；未覆盖或检查引用无法解析时不能标记 verified。
Coordinator 终检：读 Test 的证据，确认它满足任务的原始意图与验收信号（不是重测，是审证据 + 对齐意图；避免"过了字面没过意图"）。
tasks.yaml 中记录了复测证据与 resolution.verifiedBy。
用户可见行为符合验收标准。

12 KiB Raw Blame History Unescape Escape