feat: rename

kits/ack/README.md

@@ -0,0 +1,101 @@
+# ack — Agent Collaboration Kit
+
+`ack`（Agent Collaboration Kit）是一套可复用到其它项目的多 Agent 协作规范，默认三个独立角色：**Coordinator (PM) 拆解需求并调度闭环，Developer 实现与白盒验证，Test 独立黑盒复测**。关键属性是验证者 ≠ 实现者。角色默认按成本分层：Coordinator 用强模型（且不亲自跑测试），Test/Developer 用中低模型（见 `core/model-routing.md`）。
+
+当前版本见 `VERSION`。这不是 Agent Skill（无 `SKILL.md`），不由 skiff 安装，而是复制/引用到目标项目。
+
+---
+
+## 适用场景
+
+- 多个 Agent 分工协作，而非单个 Agent 从需求写到代码。
+- 需要区分规格、测试、实现、复测的责任边界（Coordinator / Test / Developer 三角色）。
+- 需要把失败项派发给 Developer，`worker_done` 后由独立的 Test 复测、Coordinator 终检。
+- 需要连续修复多个问题，并把三轮仍未修好的问题留档。
+
+---
+
+## 目录结构
+
+```text
+ack/
+  VERSION                       # kit 版本，接入时记入项目
+  README.md
+  adoption-checklist.md
+  core/                         # 稳定核心：跨项目通用，随 kit 升级，尽量别改
+    roles-and-permissions.md    #   角色/权限/状态机/完成定义（SSOT）
+    model-routing.md            #   三角色默认模型档位 + 升级规则（SSOT）
+    closed-loop.md              #   编排无关闭环 + 手动模式 + worktree 对齐
+    optimization-method.md      #   验收信号 + 三轮失败策略（SSOT）
+    prompt-templates.md         #   派发 prompt 模板
+    orca-adapter.md             #   Orca 具体命令（一种编排实现，可选）
+  templates/                    # 项目覆盖层：复制一次并填空
+    project.template.md         #   项目覆盖层模板（文件名可配置，默认不占用 AGENTS.md）
+    tasks.template.yaml
+    tasks.schema.json           #   任务板权威结构（跨语言）
+  examples/                     # 填好的最小可跑示例
+    project.example.md
+    tasks.example.yaml
+  scripts/
+    validate_tasks.py           # 校验 tasks.yaml（参考实现）
+```
+
+**核心原则**：`core/` 是稳定核心，每个概念只定义一次；`templates/` 是项目覆盖层。二者分离，让 kit 升级和项目定制互不干扰。
+
+---
+
+## 项目目录布局（推荐）
+
+每个项目在 `docs/ack/` 下只放**一个软链接**加两个项目文件，稳定核心全部走软链接：
+
+```text
+<project>/docs/ack/
+  kit -> <此框架目录>     # 唯一软链接：core/templates/examples/scripts 全在里面
+  project.md              # 项目覆盖层（差异），可改名，见下
+  tasks.yaml             # 项目任务板
+```
+
+引用稳定核心时统一走 `kit/` 前缀，例如 `docs/ack/kit/core/roles-and-permissions.md`。
+这样「一个项目一个软链接」，kit 升级自动生效，项目定制（`project.md` + `tasks.yaml`）互不干扰。
+
+## 分发方式（二选一）
+
+### 方式 A：单软链接引用（推荐，可升级）
+
+把本框架目录整体 symlink 成项目的 `docs/ack/kit`：
+
+```bash
+mkdir -p <project>/docs/ack
+ln -s <此框架绝对路径> <project>/docs/ack/kit
+```
+
+也可用 git submodule / sparse checkout 达到同样效果。项目只维护 `project.md` 与 `tasks.yaml`。
+
+### 方式 B：整份复制（简单，手动升级）
+
+把本框架整目录复制成 `docs/ack/kit/`（或直接铺平到 `docs/ack/`，此时引用去掉 `kit/` 前缀）。**务必**在 `project.md` 与 `tasks.yaml` 的 `kitVersion` 记录来源版本，日后照 `VERSION` diff 升级。
+
+### 覆盖层文件名（重要）
+
+项目差异（路径、命令、handle、模型档位）写在**项目覆盖层文件**里，**默认 `docs/ack/project.md`，不占用 `AGENTS.md`**，以免与团队已有的 `AGENTS.md` 约定冲突。文件名可配置：想让 Agent 自动加载，可在 `AGENTS.md` 加一行指向它，或直接命名为 `AGENTS.md`。无论叫什么，都在 `tasks.yaml` 的 `project.overlayFile` 记录实际路径。覆盖层只填差异，不复制 `core/` 内容。
+
+---
+
+## 快速接入
+
+1. 建 `docs/ack/`，按方式 A 建单软链接 `kit`。
+2. 复制 `kit/templates/project.template.md` → `docs/ack/project.md`，填项目差异与模型档位，记 `kitVersion`。
+3. 复制 `kit/templates/tasks.template.yaml` → `docs/ack/tasks.yaml`，填 `project`（含 `overlayFile`）与首个任务。
+4. 跑 `python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml` 确认结构。
+5. 按 `kit/core/closed-loop.md` 跑闭环（Orca 见 `kit/core/orca-adapter.md`，无 Orca 用手动模式）。
+6. 逐项对照 `kit/adoption-checklist.md`。
+
+参考 `examples/` 里填好的 `project.example.md` 与 `tasks.example.yaml`。
+
+---
+
+## 默认口令
+
+```text
+用三角色协作闭环处理 docs/ack/tasks.yaml 里的未通过项：Coordinator 派发给 Developer 修复，再交给 Test 独立复测并终检；每个问题最多修三轮，三轮仍不过就记录为遗留，然后继续下一个。
+```

kits/ack/VERSION

@@ -0,0 +1 @@
+0.6.0

kits/ack/adoption-checklist.md

@@ -0,0 +1,69 @@
+# 接入清单
+
+把本工具包引用/复制到新项目后，按此清单接入。术语与规则详见 `core/`。
+
+## 1. 分发与版本
+
+- [ ] 选定分发方式（README §「分发方式」A 单软链接 / B 复制）。
+- [ ] 在 `docs/ack/` 下建单软链接 `kit`（指向本框架）。
+- [ ] 覆盖层文件与 `tasks.yaml` 记录 `kitVersion`（对齐 `kit/VERSION`）。
+
+## 2. 项目级规范（覆盖层）
+
+- [ ] 由 `kit/templates/project.template.md` 生成覆盖层文件（默认 `docs/ack/project.md`，**不占用 `AGENTS.md`**）。
+- [ ] 在 `tasks.yaml` 的 `project.overlayFile` 记录覆盖层实际路径。
+- [ ] 覆盖层引用 `docs/ack/kit/core/`，不复制其内容。
+- [ ] 填清项目简介、技术栈、运行/构建/单测/集成测试命令。
+- [ ] 若要 Agent 自动加载覆盖层：在 `AGENTS.md` 加一行指向它，或直接命名为 `AGENTS.md`（可选）。
+
+## 2b. 模型档位
+
+- [ ] Coordinator 默认强模型且不亲自跑测试。
+- [ ] Test、Developer 默认中低模型。
+- [ ] 记录升级规则：三轮失败升级 Coordinator 复盘；复杂实现升级 Developer 档位（见 `kit/core/model-routing.md`）。
+
+## 3. 路径权限
+
+- [ ] 填实际的 Coordinator (PM) 可写路径（规格）。
+- [ ] 填实际的 Test 可写路径（集成测试、复测记录）。
+- [ ] 填实际的 Developer 可写路径（源码、单元测试、配置模板）。
+- [ ] 本地私有配置标记只读或不提交。
+- [ ] 确认 `tasks.yaml` 只有 Coordinator 写（见 `kit/core/roles-and-permissions.md`）。
+
+## 4. 任务板
+
+- [ ] 由 `kit/templates/tasks.template.yaml` 生成 `docs/ack/tasks.yaml`。
+- [ ] 替换 `<project_name>`、`<repo_path>`、`<base_url>`、`<dev_worktree>`、`overlayFile`。
+- [ ] 至少加一个真实任务，验收写成可观测信号（见 `kit/core/optimization-method.md` §1）。
+- [ ] 跑 `python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml` 通过。
+
+## 5. 编排
+
+- [ ] 决定用 Orca（`kit/core/orca-adapter.md`）还是手动模式（`kit/core/closed-loop.md`）。
+- [ ] Orca：`orca status`、`terminal list` 可用，Coordinator / Developer / Test 三个终端都在，回报能发回 Coordinator。
+- [ ] 决定用当前 worktree 还是隔离 worktree。
+
+## 6. 验证命令
+
+- [ ] Test 有黑盒复测命令，Developer 有白盒验证命令。
+- [ ] 构建产物与服务启动命令写清。
+- [ ] 浏览器测试 `BASE_URL` 写清，复测前能确认服务来自正确 worktree。
+
+## 7. 三轮失败策略
+
+- [ ] 每个任务记录 `dispatch.rounds`。
+- [ ] 三轮失败标记 `leftover` 并填 `resolution.leftoverReason`。
+- [ ] `leftover` 不阻塞其它任务；最终报告列出所有 `leftover` 与最后失败证据。
+
+## 8. 第一次试运行
+
+选一个低风险 bug 跑完整闭环，结束后检查是否出现：
+
+- Developer 修改了越权路径，或 Test 改了源码。
+- worker_done 或复测报告没有验证证据。
+- Test 复测到了旧服务。
+- Coordinator 没做终检就直接 verified。
+- 任务板字段不够记录失败原因。
+- 三轮失败策略没被执行。
+
+把发现的问题回写到项目覆盖层文件；若属通用问题，回流到 kit 的 `kit/core/` 并升 `VERSION`。

kits/ack/core/closed-loop.md

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

kits/ack/core/model-routing.md

@@ -0,0 +1,69 @@
+# 模型路由（稳定核心）
+
+本文件是**三角色默认模型档位**和**升级规则**的单一事实源（SSOT）。目标：在不牺牲质量的前提下降低 token 和模型成本——把昂贵的强模型留给需要判断的工作，把机械执行交给较弱模型。
+
+角色定义见 `roles-and-permissions.md`（Coordinator 编排 / Test 验证 / Developer 实现）。本文件只补一层正交的「用哪个档位的模型」。
+
+---
+
+## 默认档位
+
+| 角色 | 默认模型档位 | 理由 |
+|------|--------------|------|
+| Coordinator (PM) | 强模型 | 需求拆解、验收信号设计、优先级、终检对齐意图、三轮失败复盘都需要高质量推理 |
+| Test | 中低模型 | 按既定验收信号执行浏览器/API/脚本，主要做观察、记录、逐条 pass/fail |
+| Developer | 中低模型（按任务升级） | 多数实现可照规格执行；跨系统、数据迁移、重复失败时再升级 |
+
+关键点：Coordinator 用强模型但**不亲自跑测试**（测试由 Test 承担），所以强模型的 token 花在思考和终检上，而不是反复点击页面、跑 smoke、复制日志。这一分工天然省 token，同时保持「验证者 ≠ 实现者」。
+
+---
+
+## 什么时候用强模型
+
+- 新需求理解、产品取舍、范围决策。
+- 架构与数据模型决策。
+- 把验收写成可观测信号（见 `optimization-method.md` §1）。
+- 需求含糊、规格与实现/测试冲突时的裁决。
+- Coordinator 终检：读证据、对齐原始意图。
+- 重复失败后的根因复盘与重新拆分。
+
+## 什么时候用中低模型
+
+- Test：跑浏览器用例、API smoke、逐条比对期望与实际、产出证据。
+- Developer：从清晰规格实现范围明确的任务、跑构建与单测、回报 worker_done。
+
+---
+
+## 升级规则
+
+**升级到 Coordinator（强模型）复盘**，当：
+
+- 同一验收路径 Developer 连续失败三轮（见 `optimization-method.md` §4）。
+- Test 两次仍无法给出清晰失败证据。
+- 任务需要改动产品范围或验收标准。
+- 修复涉及持久化数据、破坏性文件操作、安全或回滚。
+- 规格、测试、实现三者出现冲突。
+
+**升级 Developer 模型档位**，当：
+
+- 任务横跨多个子系统。
+- 改动涉及数据模型或迁移。
+- 需要设计新的抽象。
+- 低档位反复产出表面修复。
+
+升级动作本身由 Coordinator 判断并记录（可写进 `tasks.yaml` 的 `dispatch` 备注或 `resolution`）。
+
+---
+
+## 成本原则
+
+强模型产出高密度、可复用的产物：需求、架构决策、验收信号、任务拆分、失败复盘。
+中低模型消费这些产物，产出可核对的执行证据：测试结果、快照、API 响应、构建日志、改动文件清单。
+
+这样把昂贵推理挡在重复执行之外。
+
+---
+
+## 一句话
+
+Coordinator 是脑，Test 是眼，Developer 是手。脑用最强的模型且不做机械测试，眼和手用便宜模型，只有常规闭环卡住时才升级。

kits/ack/core/optimization-method.md

@@ -0,0 +1,150 @@
+# 优化方法（稳定核心）
+
+减少"开发声称完成但复测不过"的循环成本。本文件是**验收信号写法**和**三轮失败策略**的 SSOT，其它文件引用这里。
+
+三角色分工（Coordinator 编排 / Test 验证 / Developer 实现）见 `roles-and-permissions.md`；复测步骤、Coordinator 终检与环境对齐见 `closed-loop.md`。
+
+---
+
+## 1. 先把验收写成可观测信号（SSOT）
+
+不要只写"页面可用""体验更好"。每个任务至少写三类信号：
+
+| 类型 | 示例 |
+|------|------|
+| 可见文本 | 页面出现 `确认应用标签`、`取消`、`将修改` |
+| API 结果 | `POST /api/...` 返回 `code=0` 且字段存在 |
+| 交互结果 | 点击按钮后出现确认区；取消后不触发写入 |
+
+好的验收：
+
+```text
+点击"预览变更"后，页面必须出现 API 返回的 diff 行：
+- title
+- 修改前值
+- 修改后值
+- coverChanged 提示
+```
+
+不好的验收：
+
+```text
+预览功能正常。
+```
+
+---
+
+## 2. 回报必须带证据，不带结论
+
+Developer 的 `worker_done` 应报告：改了哪些文件、跑了哪些命令、自己如何复现验收路径、仍可能有的风险。Test 的复测报告同理：跑了哪些命令、命中/缺失了哪些验收信号、实际观察到什么、证据（snapshot / API 结果）。两者的"结论"都不作数，只有 Coordinator 落盘的 `tasks.yaml` 才是事实。
+
+不要写：
+
+```text
+已完成，应该可以了。
+```
+
+要写：
+
+```text
+修改 web/app/fix/page.tsx。已运行 npm run build、go test ./...。
+手测 /fix?fileId=1：搜索、选择候选、预览、确认区都可见。
+风险：未执行真实写文件 apply。
+```
+
+---
+
+## 3. 验证权在 Test，Coordinator 只信证据
+
+即使 Developer 的 worker_done 写了"全部通过"，也必须由独立的 Test 复测（验证者 ≠ 实现者）。完整复测步骤与 worktree/服务对齐见 `closed-loop.md`。独立复测可避免三类假通过：测错服务实例、测到旧构建产物、开发只验证静态文本没验证真实交互。
+
+Coordinator 不亲自复测，但要做终检：读 Test 的证据，确认它覆盖了每条验收信号且符合原始意图，避免"过了字面没过意图"。终检不通过就回写 `failed_retest`。
+
+---
+
+## 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. 优先让测试可执行化
+
+如果某个问题需要多轮修复，说明它值得沉淀成自动化检查。这类可执行测试由 Test 拥有并维护（见 `roles-and-permissions.md` 权限表的 `<integration_test_paths>`）。优先级：
+
+1. API smoke。
+2. 浏览器脚本或 case 文档。
+3. 单元测试。
+4. 人工检查清单。
+
+目标不是全部自动化，而是把最容易反复误判的路径自动化。
+
+---
+
+## 9. 结束条件
+
+一轮闭环结束时，必须能回答：
+
+- 哪些任务 verified？哪些 leftover？
+- 每个 leftover 失败了几轮？最后一轮失败证据是什么？
+- 当前工作树有哪些未提交改动？
+- 是否还有 open / failed_retest 未处理？
+
+答不清楚，闭环就还没结束。

kits/ack/core/orca-adapter.md

@@ -0,0 +1,171 @@
+# 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、Test 三个终端都存在；Developer 在正确 worktree；当前没有冲突的活跃编排任务。
+
+---
+
+## 创建父任务
+
+```bash
+orca orchestration task-create --spec "$(cat <<'EOF'
+Goal: Complete <release_or_feature> with supervised Coordinator -> Developer -> Test loop.
+
+Coordinator (PM): owns task board, decomposition, dispatch, and final gate (reads Test evidence, does not test).
+Developer: owns implementation and white-box verification.
+Test: owns independent black-box retest and evidence (verifier != implementer).
+
+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 and retest reports are not final completion; only Coordinator writes tasks.yaml.
+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: <overlay_file> (project overlay), tasks.yaml, <relevant_spec_or_test_doc>
+Failure evidence: <copy latest Test evidence>
+Acceptance: <copy expected behavior + verification commands>
+
+Constraints:
+- Follow the overlay file 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
+```
+
+---
+
+## 派发给 Test 复测
+
+Developer 回报 worker_done、Coordinator 写回 `fixed_by_dev` 后，把复测任务发给 Test：
+
+```bash
+orca orchestration dispatch --task <task_id> --to <test_handle> --inject --json
+```
+
+不能 `--inject` 时，先登记再手动投递 `prompt-templates.md` §3 的复测派发 prompt：
+
+```bash
+orca orchestration dispatch --task <task_id> --to <test_handle> --json
+orca terminal send --terminal <test_handle> --text "$(cat <<'EOF'
+<粘贴 prompt-templates.md §3 复测派发模板，已填占位符>
+EOF
+)" --enter --json
+```
+
+---
+
+## 等待结果
+
+```bash
+orca orchestration check \
+  --terminal <coordinator_handle> \
+  --wait \
+  --types worker_done,retest_result,escalation,decision_gate \
+  --timeout-ms 900000 \
+  --json
+```
+
+等待超时不等于失败。长任务可继续等待，或检查 worker 终端活性。`worker_done` 来自 Developer，`retest_result`（无该类型时用 `worker_done` + subject 区分）来自 Test。
+
+---
+
+## 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 写回 `fixed_by_dev`，再按上文派发给 Test 复测。
+
+---
+
+## Test 回报复测结果
+
+字段含义见 `prompt-templates.md` §5：
+
+```bash
+orca orchestration send \
+  --to <coordinator_handle> \
+  --type retest_result \
+  --subject "<task_id> retest round <n>" \
+  --body "<逐条验收信号结论 + 实际观察 + 证据>" \
+  --payload '{
+    "taskId": "<orca_task_id>",
+    "dispatchId": "<orca_dispatch_id>",
+    "env": {"worktree": "<path>", "branch": "<branch>", "commit": "<sha>", "baseUrl": "<base_url>"},
+    "signals": ["<signal 1>: pass", "<signal 2>: fail (<evidence>)"],
+    "conclusion": "all-signals-pass | signals-failed"
+  }' \
+  --json
+```
+
+无 `retest_result` 类型时用 `--type worker_done`，靠 subject `retest round <n>` 区分。收到复测结果后，Coordinator 按 `closed-loop.md` 做终检并回写 `tasks.yaml`：通过 `verified`，不过 `failed_retest`。

kits/ack/core/prompt-templates.md

@@ -0,0 +1,166 @@
+# 派发 Prompt 模板（稳定核心）
+
+Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发复测。复制时替换尖括号占位符。模板与编排工具无关：Orca 模式用 `orca-adapter.md` 的命令投递，手动模式直接把文本发给对应 Agent。
+
+角色分工见 `roles-and-permissions.md`；闭环顺序见 `closed-loop.md`。
+
+---
+
+## 1. 初始派发给 Developer
+
+```text
+你现在接到一个受监督的协作任务。请在 <dev_worktree> 开发工作树内完成。
+
+任务：
+- 修复 <task_id>: <task_title>
+
+请先读取：
+- <overlay_file>（项目覆盖层，路径见 tasks.yaml 的 project.overlayFile）
+- tasks.yaml
+- <relevant_spec_or_test_doc>
+
+当前失败证据：
+<copy latest Test evidence>
+
+验收标准（可观测信号，见 optimization-method.md §1）：
+1. <expected behavior 1>
+2. <expected behavior 2>
+3. <expected behavior 3>
+
+约束：
+- 只修改 Developer 可写路径（见覆盖层文件的权限表）。
+- 不要修改产品规格和集成测试文件（分别由 Coordinator 与 Test 拥有），除非任务明确要求。
+- 不要写 tasks.yaml，不要标记 verified。
+- 不要提交或推送，除非用户明确要求。
+- 最小 diff，避免无关重构。
+
+完成前必须运行：
+- <test command 1>
+- <test command 2>
+
+完成后回报一次 worker_done（格式见 §4）。如果阻塞，请发送 escalation 或 ask。
+```
+
+---
+
+## 2. 复测失败再派发给 Developer
+
+```text
+第 <n> 轮复测未通过，请继续修 <task_id>。
+
+上一轮开发声称：
+<worker_done summary>
+
+Test 独立复测结果：
+- 运行命令：<commands>
+- 失败页面/API：<page or endpoint>
+- 仍缺失：<missing expected checks>
+- 实际观察：<actual evidence>
+
+关键提示：
+- 不要只满足静态文案，必须满足交互后的真实状态。
+- 如果后端/API 正常而 UI 不更新，请优先排查事件链、状态重置、异步请求、构建产物和服务 worktree。
+- 修复后请自己用浏览器或脚本复现 Test 的完整步骤。
+
+验收不变：
+<copy acceptance criteria>
+
+完成后回报 worker_done，subject 使用："<task_id> fix ready round <n>"
+```
+
+---
+
+## 3. 派发给 Test 复测
+
+Developer 回报 worker_done 后，Coordinator 把复测任务发给 Test。
+
+```text
+请对 <task_id>: <task_title> 做独立黑盒复测。
+
+请先读取：
+- <overlay_file>（项目覆盖层，路径见 tasks.yaml 的 project.overlayFile）
+- tasks.yaml（该任务的验收信号）
+- <relevant_spec_or_test_doc>
+
+Developer 本轮声称（仅供参考，不作数）：
+- 改动文件：<files>
+- 自测命令：<commands>
+
+复测要求：
+- 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 closed-loop.md）。
+- 逐条验证下列验收信号，不要只看静态文案，要验证交互后的真实状态：
+  1. <observable signal 1>
+  2. <observable signal 2>
+  3. <observable signal 3>
+- 需要时把易反复误判的路径沉淀成可执行测试（见 optimization-method.md §8）。
+
+约束：
+- 只读源码，不修改应用代码，不写 tasks.yaml。
+- 只回传证据和逐条结论，最终判定由 Coordinator 终检后落盘。
+
+完成后回报一次复测报告（格式见 §5），subject："<task_id> retest round <n>"。
+```
+
+---
+
+## 4. Developer 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」的命令发送同样的字段。
+
+---
+
+## 5. Test 复测报告格式
+
+Test 只回传证据和逐条结论，不下最终判定：
+
+```text
+subject: <task_id> retest round <n>
+env:
+  worktree: <path>
+  branch: <branch>
+  commit: <short sha>
+  baseUrl: <base_url>
+commands:
+  - <command_a>: passed/failed
+signals:
+  - <signal 1>: pass/fail (<evidence>)
+  - <signal 2>: pass/fail (<evidence>)
+browser: <snapshot / DOM / API evidence>
+conclusion: all-signals-pass / signals-failed
+notes: <observations, suspected cause if failed>
+```
+
+Orca 模式下用 `orca-adapter.md` §「Test 回报复测结果」的命令发送同样的字段。
+
+---
+
+## 6. Coordinator 最终报告模板
+
+```text
+本轮闭环完成。
+
+已验证（Test 复测通过 + 终检）：
+- <task_id>: <what passed>
+
+遗留：
+- <task_id>: 三轮仍未通过，已记录为 leftover。最后失败证据：<evidence>
+
+验证命令：
+- <command>: passed
+
+工作树状态：
+- <repo_path>: <git status summary>
+- <dev_worktree>: <git status summary>
+```

kits/ack/core/roles-and-permissions.md

@@ -0,0 +1,98 @@
+# 角色与权限（稳定核心）
+
+本文件是**角色模型、路径权限、任务状态机、完成定义**的单一事实源（SSOT）。其它文件只引用本文件，不重复定义。
+
+目标：让每个 Agent 只处理自己能验证的事情，减少上下文污染和越权修改。
+
+---
+
+## 角色模型（三角色）
+
+本 kit 默认三个独立 Agent：**Coordinator 只编排、Test 只验证、Developer 只实现**。关键属性是**验证者 ≠ 实现者**：Developer 不能给自己盖章，验证权在独立的 Test。
+
+| 角色 | 主要职责 | 验证方式 | 不应做的事 |
+|------|----------|----------|------------|
+| 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` 才算数。
+
+**模型档位（正交层）。** 三角色默认按成本分层：Coordinator 用强模型，Test 与 Developer 用中低模型，必要时升级。完整档位表与升级规则见 `model-routing.md`。Coordinator 用强模型但不跑测试，这一分工天然省 token 又不破坏「验证者 ≠ 实现者」。
+
+---
+
+## 路径权限模板
+
+目标项目在自己的**覆盖层文件**中填入实际路径（模板见 `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 | 见下方「任务板写入约定」 |
+
+---
+
+## 任务状态机（SSOT）
+
+```text
+open
+  -> dispatched      （派发给 Developer）
+  -> fixed_by_dev    （Developer 声称已修）
+  -> retesting       （派发给 Test 复测）
+  -> verified        （Test 通过 + Coordinator 终检）
+```
+
+失败分支：
+
+```text
+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` 是持久事实源，为避免多 Agent 并发写冲突：
+
+- **只有 Coordinator 写 `tasks.yaml`**。Test 与 Developer 对它都是只读的。
+- Developer 的实现状态、Test 的复测证据都通过消息回传（`worker_done` / 复测报告），由 Coordinator 落盘。
+- 每次写入前先读最新内容，写入后更新顶层 `updatedAt`。
+- 单次写入应是一个任务的一次状态跃迁，避免整表批量重写。
+
+---
+
+## 完成定义（Definition of Done）
+
+一个任务只有同时满足以下条件，才能标记 `verified`：
+
+- Developer 已提供修改文件和白盒验证证据（`worker_done`）。
+- Test 在正确 worktree 和正确服务实例上独立复测通过（对齐检查见 `closed-loop.md`），并产出可观测证据。
+- 相关单元测试、构建、集成或浏览器检查通过。
+- **Coordinator 终检**：读 Test 的证据，确认它满足任务的原始意图与验收信号（不是重测，是审证据 + 对齐意图；避免"过了字面没过意图"）。
+- `tasks.yaml` 中记录了复测证据与 `resolution.verifiedBy`。
+- 用户可见行为符合验收标准。

kits/ack/examples/project.example.md

@@ -0,0 +1,78 @@
+# notes-web Agent 协作协议（示例，项目覆盖层）
+
+> 本项目基于 ack v0.6.0。
+> 稳定规范引用 `docs/ack/kit/core/`，本文件只填项目差异。
+> 覆盖层文件放在 `docs/ack/project.md`，不占用 `AGENTS.md`。
+> 目录下只有一个软链接 `kit/` + `project.md` + `tasks.yaml`。
+
+## 项目概览
+
+- 项目：`notes-web`
+- 技术栈：`TypeScript + React (Vite) + Go`
+- 运行命令：`npm run dev`（前端）、`go run ./server`（后端）
+- Base URL：`http://localhost:5173`
+- 任务板：`docs/ack/tasks.yaml`
+- 覆盖层文件：`docs/ack/project.md`
+
+## 稳定规范（引用，不重复）
+
+- 角色 / 权限 / 状态机 / 完成定义：`docs/ack/kit/core/roles-and-permissions.md`
+- 模型档位与升级规则：`docs/ack/kit/core/model-routing.md`
+- 闭环流程（含手动模式、worktree 对齐）：`docs/ack/kit/core/closed-loop.md`
+- 优化方法（验收信号、三轮策略）：`docs/ack/kit/core/optimization-method.md`
+- 派发 prompt 模板：`docs/ack/kit/core/prompt-templates.md`
+- Orca 编排命令：`docs/ack/kit/core/orca-adapter.md`
+
+## 模型档位
+
+| 角色 | 默认档位 | 本项目实际 |
+|------|----------|------------|
+| Coordinator (PM) | 强模型 | claude-sonnet-5-thinking-high |
+| Test | 中低模型 | 默认（中低） |
+| Developer | 中低模型 | 默认（中低），架构任务临时升级 |
+
+## 路径权限
+
+| 路径 | Coordinator | Test | Developer | 说明 |
+|------|:-----------:|:----:|:---------:|------|
+| `docs/spec/**` | R/W | Read-only | Read-only | 产品规格（PM 拥有） |
+| `tests/browser/**` | Read-only | R/W | Read-only | 浏览器回归用例（Test 拥有） |
+| `.qa-records/**` | Read-only | R/W | Read-only | 复测记录（gitignore） |
+| `web/**`、`server/**` | Read-only | Read-only | R/W | 应用源码 |
+| `**/*_test.go`、`web/**/*.test.tsx` | Read-only | Read-only | R/W | 单元测试 |
+| `config/*.example.*` | Read-only | Read-only | R/W | 可提交配置模板 |
+| `.env`、`config/local.*` | Read-only | Read-only | Read-only | 本地私有配置 |
+| `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 |
+
+## 命令
+
+Developer 白盒验证：
+
+```bash
+npm run build
+go test ./...
+npm run dev   # 本地起前端
+```
+
+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/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
+```
+
+## 硬规则（其余见 kit/core/）
+
+- 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现。
+- 模型分层：Coordinator 强模型不跑测试，Test/Developer 中低模型（见 kit/core/model-routing.md）。
+- `worker_done` 与复测报告都不等于完成，必须 Test 独立复测 + Coordinator 终检后才能 `verified`。
+- 只有 Coordinator 写 `tasks.yaml`；Test 与 Developer 只读。
+- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续。
+- 不提交或推送，除非用户明确要求。

kits/ack/examples/tasks.example.yaml

@@ -0,0 +1,115 @@
+# 填好的最小示例（虚构的 notes-web 项目）。可用 scripts/validate_tasks.py 校验通过。
+version: 1
+updatedAt: "2026-07-06T09:40:00+08:00"
+source: "Coordinator (PM) Agent"
+kitVersion: "0.3.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"
+      verifiedBy: "test-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
+      verifiedBy: null
+      verifiedAt: null
+      leftoverReason: "failed after 3 supervised developer rounds; 需重新设计并发模型"

kits/ack/scripts/validate_tasks.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""校验 tasks.yaml 是否符合 ack 任务板结构。
+
+权威结构是同目录上层的 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/ack/templates/project.template.md

@@ -0,0 +1,83 @@
+# <项目名> Agent 协作协议（项目覆盖层）
+
+> 本项目基于 ack v<kit_version>（见 `docs/ack/kit/VERSION`）。
+> 稳定规范引用 `docs/ack/kit/core/`，不复制其内容；本文件只填项目自己的差异。
+>
+> **本文件是「项目覆盖层」，文件名可配置。** 默认放 `docs/ack/project.md`，
+> 不占用 `AGENTS.md`，避免与团队已有的 `AGENTS.md` 约定冲突。
+> 若希望 Agent 自动加载，可在项目 `AGENTS.md` 里加一行指向本文件，或直接把本文件命名为 `AGENTS.md`。
+> 无论叫什么，都在 `tasks.yaml` 的 `project.overlayFile` 记录实际路径。
+>
+> 目录约定：`docs/ack/` 下只有一个软链接 `kit/`（指向共享框架），加本项目 `project.md` + `tasks.yaml`。
+
+## 项目概览
+
+- 项目：`<project_name>`
+- 技术栈：`<tech_stack>`
+- 运行命令：`<run_command>`
+- Base URL：`<base_url>`
+- 任务板：`docs/ack/tasks.yaml`
+- 覆盖层文件：`<overlay_file_path>`（默认 `docs/ack/project.md`）
+
+## 稳定规范（不在此重复，直接引用）
+
+- 角色模型 / 权限 / 状态机 / 完成定义：`docs/ack/kit/core/roles-and-permissions.md`
+- 模型档位与升级规则：`docs/ack/kit/core/model-routing.md`
+- 闭环流程（含手动模式、worktree 对齐）：`docs/ack/kit/core/closed-loop.md`
+- 优化方法（验收信号、三轮策略）：`docs/ack/kit/core/optimization-method.md`
+- 派发 prompt 模板：`docs/ack/kit/core/prompt-templates.md`
+- Orca 编排命令（可选）：`docs/ack/kit/core/orca-adapter.md`
+
+## 模型档位（项目可覆盖，默认见 core/model-routing.md）
+
+| 角色 | 默认档位 | 本项目实际 |
+|------|----------|------------|
+| Coordinator (PM) | 强模型 | `<model_or_default>` |
+| Test | 中低模型 | `<model_or_default>` |
+| Developer | 中低模型 | `<model_or_default>` |
+
+## 路径权限（项目覆盖层，必须填实际路径）
+
+| 路径 | Coordinator | Test | Developer | 说明 |
+|------|:-----------:|:----:|:---------:|------|
+| `<spec_paths>` | R/W | Read-only | Read-only | 产品规格、API 文档、计划（PM 拥有） |
+| `<integration_test_paths>` | Read-only | R/W | Read-only | 浏览器/API 回归（Test 拥有） |
+| `<test_records_path>` | Read-only | R/W | Read-only | 复测记录 |
+| `<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_paths>` | Read-only | Read-only | Read-only | 本地私有配置 |
+| `tasks.yaml` | R/W | Read-only | Read-only | 只有 Coordinator 写 |
+
+## 命令（项目覆盖层）
+
+Developer 白盒验证：
+
+```bash
+<unit_test_command>
+<build_command>
+<local_run_command>
+```
+
+Test 黑盒复测：
+
+```bash
+<preflight_command>
+<api_smoke_command>
+<browser_regression_command>
+```
+
+任务板校验：
+
+```bash
+python3 docs/ack/kit/scripts/validate_tasks.py docs/ack/tasks.yaml
+```
+
+## 硬规则（其余见 kit/core/）
+
+- 三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现（验证者 ≠ 实现者）。
+- 模型分层：Coordinator 用强模型且不亲自跑测试，Test/Developer 用中低模型，必要时升级（见 kit/core/model-routing.md）。
+- `worker_done` 与复测报告都不等于完成。必须 Test 独立复测 + Coordinator 终检后才能 `verified`。
+- 只有 Coordinator 写 `tasks.yaml`；Developer 与 Test 都只读，通过消息回报。
+- 每个任务最多派发 3 轮，仍不过标记 `leftover` 并继续下一个。
+- 不提交或推送，除非用户明确要求。

kits/ack/templates/tasks.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://git.yumee.top/laily/skills/kits/ack/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": "接入时所基于的 ack 版本，便于日后 diff 升级"
+    },
+    "project": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string" },
+        "repoPath": { "type": "string" },
+        "baseUrl": { "type": "string" },
+        "devWorktree": { "type": "string" },
+        "overlayFile": {
+          "type": "string",
+          "description": "项目覆盖层文件路径，默认 docs/ack/project.md，可自定义"
+        }
+      }
+    },
+    "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"] },
+            "verifiedBy": { "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/ack/templates/tasks.template.yaml

@@ -0,0 +1,69 @@
+# 复制为 docs/ack/tasks.yaml，替换占位符。结构见 templates/tasks.schema.json。
+version: 1
+updatedAt: "<YYYY-MM-DDTHH:mm:ss+TZ>"
+source: "Coordinator (PM) Agent"
+kitVersion: "<接入时的 ack 版本，见 kit 根 VERSION>"
+project:
+  name: "<project_name>"
+  repoPath: "<repo_path>"
+  baseUrl: "<base_url>"
+  devWorktree: "<dev_worktree>"
+  overlayFile: "docs/ack/project.md"
+
+summary:
+  verified: []
+  open: []
+  failedRetest: []
+  leftovers: []
+
+tasks:
+  - id: "BUG-001"
+    type: "bug"
+    title: "<short title>"
+    priority: "P0"
+    status: "open"
+    assignee: "developer"
+    component: "<source file or module>"
+    specRefs:
+      - "<docs/spec.md#section>"
+    testRefs:
+      - "<tests/browser/cases/01-case.md>"
+
+    description: >
+      <What is wrong, in user-visible terms.>
+
+    stepsToReproduce:
+      - "<step 1>"
+      - "<step 2>"
+
+    expected: >
+      <Expected behavior.>
+
+    actual: >
+      <Actual behavior observed by Test.>
+
+    evidence:
+      browser: "<snapshot text, screenshot path, or UI finding>"
+      api: "<curl result or API mismatch>"
+      logs: "<relevant log line if any>"
+
+    verification:
+      commands:
+        - "<unit/build command>"
+        - "<browser/API smoke command>"
+      browser:
+        page: "<page path>"
+        checks:
+          - "<visible text or interaction expected>"
+
+    dispatch:
+      taskId: null
+      dispatchId: null
+      worker: null
+      rounds: []
+
+    resolution:
+      fixedBy: null
+      verifiedBy: null
+      verifiedAt: null
+      leftoverReason: null