feat(ack): add project knowledge guardrails

skills/ack/references/adoption-checklist.md

@@ -4,7 +4,9 @@
 
 - [ ] ACK Skill 已全局安装或安装到当前项目。
 - [ ] 已运行 `skiff init ack --project <project-root>`。
-- [ ] `docs/ack/` 只包含项目自己的 `project.md` 与 `tasks.yaml`。
+- [ ] `docs/ack/` 只包含项目自己的 `project.md`、`tasks.yaml` 与 `knowledge.yaml`。
+- [ ] 旧项目缺少 `knowledge.yaml` 时，只补空文件及缺失的
+      `project.knowledgeFile` 指针，没有重跑初始化或覆盖其它项目状态。
 - [ ] 项目中没有 ACK Skill 的复制目录或 `kit`、`framework` 软链接。
 - [ ] `tasks.yaml` 使用 `ackVersion` 记录 ACK Skill 版本。
 
@@ -12,6 +14,8 @@
 
 - [ ] `project.md` 只保存项目差异，不复制 Skill 的通用规范。
 - [ ] `tasks.yaml` 的 `project.overlayFile` 指向实际覆盖层。
+- [ ] `tasks.yaml` 的 `project.knowledgeFile` 固定为
+      `docs/ack/knowledge.yaml`。
 - [ ] 技术栈、运行、构建、单测和集成测试命令均来自项目证据。
 - [ ] Coordinator、Developer、Test 的模型档位和升级规则已明确。
 
@@ -22,6 +26,7 @@
 - [ ] Developer 可写源码与单元测试，但不能改规格或黑盒验收。
 - [ ] 私有配置只读且不提交。
 - [ ] `tasks.yaml` 只有 Coordinator 写。
+- [ ] `knowledge.yaml` 只有 Coordinator 写；Developer 与 Test 只通过回报提名或验证。
 
 ## 任务板
 
@@ -30,12 +35,30 @@
 - [ ] 真实任务的验收是可观测信号。
 - [ ] 已运行 `<ack-skill-dir>/scripts/validate_tasks.py` 并通过。
 
+## 项目知识
+
+- [ ] 新项目没有已验证知识时使用 `verificationRegistry: {}` 与 `entries: []`，
+      不虚构 active 条目。
+- [ ] 已运行 `<ack-skill-dir>/scripts/validate_knowledge.py` 并通过；同时校验任务引用。
+- [ ] Coordinator 只从 `active` 条目按 scope 推荐知识，并显式确认固定 revision 的
+      `knowledgeRefs`。
+- [ ] `candidate` 留在任务证据中，不派发；`stale`、`superseded`、`archived`
+      不默认选择。
+- [ ] 每轮只内联命中的少量知识，不全量注入 `knowledge.yaml`。
+- [ ] Developer 回报 `knowledgeApplied` 与 `knowledgeCandidates`，Test 回报
+      `knowledgeChecks`。
+- [ ] `verification.ref` 只引用 `verificationRegistry` 中已审查的仓库内相对 path
+      和结构化 args；执行时只把 registry ID 交给 `run_verification.py`，不从
+      知识正文或选择器输出拼接 shell。
+- [ ] 关键约束已规划下沉到测试、lint、CI 或正式规范。
+- [ ] ACK 不自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
+
 ## 编排
 
 - [ ] 已选择 Orca 或手动模式。
 - [ ] 派发前优先复用同 worktree、同角色、同配置的空闲 worker。
 - [ ] Developer 与 Test 的启动命令通过校验。
-- [ ] 多 worktree 场景只有一个权威 `tasks.yaml`。
+- [ ] 多 worktree 场景只有一个权威 `tasks.yaml` 和 `knowledge.yaml`。
 - [ ] Test 使用的服务来自正确 worktree。
 
 ## 闭环
@@ -48,4 +71,5 @@
 
 首次接入建议选择一个低风险问题跑完整闭环。项目差异写回
 `docs/ack/project.md`；通用问题回流到 ACK Skill 的 `references/`、`templates/`
-或 `scripts/`，并更新 `VERSION`。
+或 `scripts/`，并更新 `VERSION`。项目特有、跨任务复用且已经验证的经验才写入
+`docs/ack/knowledge.yaml`。

skills/ack/references/closed-loop.md

@@ -2,7 +2,10 @@
 
 本文件定义**与具体编排工具无关**的三角色协作闭环。运行时调度可以用 Orca（见 `orca-adapter.md`），也可以手动跑（见下方「手动模式」）。
 
-原则：调度消息只是运行时载体，**所有结论都必须回写到 `tasks.yaml`**（事实源），不要把消息当最终记录。角色定义见 `roles-and-permissions.md`：Coordinator 只编排、Test 只验证、Developer 只实现。
+原则：调度消息只是运行时载体，任务结论必须回写到 `tasks.yaml`；跨任务复用、已经
+验证的项目经验必须由 Coordinator 回写到 `knowledge.yaml`。不要把消息当最终记录。
+角色定义见 `roles-and-permissions.md`：Coordinator 只编排、Test 只验证、
+Developer 只实现。
 
 ---
 
@@ -12,12 +15,12 @@
 
 | 抽象动作 | 含义 | Orca 实现 | 手动实现 |
 |----------|------|-----------|----------|
-| `prepare(task)` | Coordinator 把任务和验收信号写进 `tasks.yaml` | 同左 | 同左 |
+| `prepare(task)` | Coordinator 把任务和验收信号写进 `tasks.yaml`，按 scope 推荐知识并确认显式 `knowledgeRefs` | 同左 | 同左 |
 | `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` | 同左 | 同左 |
+| `gate(task)` | Coordinator 读 Test 证据、`knowledgeChecks` 并对齐原始意图（不重测） | 同左 | 同左 |
+| `writeback(task, result)` | Coordinator 把任务结果写回 `tasks.yaml`，把验证通过的跨任务经验按权限写入 `knowledge.yaml` | 同左 | 同左 |
 
 派发用的 prompt 见 `prompt-templates.md`。状态流转见 `roles-and-permissions.md` §「任务状态机」。**独立复测由 Test 执行，不是 Coordinator**；Coordinator 只做读证据的终检。
 
@@ -28,13 +31,15 @@
 ```text
 Coordinator 发现或读取 open 任务
   -> prepare：写/补全 tasks.yaml 验收信号
+  -> 从 knowledge.yaml 按 scope 推荐 active 知识，Coordinator 确认固定 revision 的 knowledgeRefs
+  -> 为新轮次生成稳定 attemptId（<task-id>-A<round>），Developer 与 Test 共用
   -> 决定 worktree：当前 worktree 起子 agent，还是新建隔离 worktree（见下节「子任务放哪」）
   -> 解析 worker：先复用同 worktree、同角色的空闲 worker；没有可复用项时才校验命令并新建（见 orca-adapter.md）
   -> dispatch 给 Developer（--to <worker handle>）
-  -> wait：Developer 的 worker_done / escalation
+  -> wait：Developer 的 worker_done / escalation（含 knowledgeApplied / knowledgeCandidates）
   -> writeback fixed_by_dev
   -> dispatch 给 Test（retesting）
-  -> wait：Test 的 retest_result
+  -> wait：Test 的 retest_result（含 knowledgeChecks 和 candidate 独立证据）
   -> Test 通过：gate（Coordinator 读证据对齐意图）
         -> 通过 gate：writeback verified
         -> gate 不满足意图：writeback failed_retest，带意图差异再派发 Developer
@@ -44,6 +49,51 @@ Coordinator 发现或读取 open 任务
 
 一次派发只修一个明确问题（细则见 `optimization-method.md` §「每轮派发只修一个明确问题」）。
 「决定 worktree」「解析 worker」两步的决策见下节与 `model-routing.md` / `orca-adapter.md`。
+Coordinator 默认给新逻辑轮次生成 `<task-id>-A<round>`，并在记录轮次结果时写入
+`tasks[].dispatch.rounds[].attemptId`。它独立于编排工具产生的 `taskId` 和
+`dispatchId`：前者用于知识来源追溯，后两者只用于查询运行时。0.9.0 之前的历史
+轮次允许暂时缺省；但要把该轮证据晋升为知识前，必须按确定性格式补齐。晋升时，
+`provenance.taskId` 和 `provenance.attemptId` 必须能精确回到该任务及轮次。
+
+### 知识选择与晋升
+
+`prepare(task)` 时可以使用 Skill 自带的 `scripts/select_knowledge.py` 按
+component、path、dependency、version 和 tag 确定性推荐条目。选择器只返回
+`active`，并受条目数限制；`stale`、`superseded` 和 `archived` 不默认派发。自动
+匹配只是推荐。条目中每个非空 scope 维度都必须被任务上下文命中，因此调用时应
+提供当前任务已知的全部 component、path、dependency、version、tag、symbol 和错误
+特征。Coordinator 确认并写入当前任务的显式 `knowledgeRefs` 后才成为本轮权威
+上下文。
+
+`scope.paths` 使用 POSIX 路径 glob：`*` 不跨目录分隔符，`**` 才能跨目录。多个
+pattern 是同一维度内的 OR，候选越多表示范围越宽；超过选择预算时，选择器优先保留
+命中维度更多、OR 候选更少、字面约束更多且通配符更少的条目。
+
+派发时只内联本轮引用的少量知识，不要求 worker 全量读取 `knowledge.yaml`。这也
+避免隔离 worktree 读不到 Coordinator 工作树中尚未提交的项目状态。
+
+进行中的任务只能引用 `active` 条目。已经进入 `verified` 或 `leftover` 的终态任务
+可以继续保留固定 revision 的历史引用，即使对应知识后来变成 `stale`、
+`superseded` 或 `archived`；这些旧条目不会再次被选择器派发。
+
+Developer 或 Test 发现经验时只能通过 `knowledgeCandidates` 提名，并带上当前任务
+的独立观测、scope、触发条件和证据。candidate 留在任务证据中，不进入知识选择器，
+也不能被下一轮当作 active 指令。只有 Test 独立验证、Coordinator gate 通过后，
+Coordinator 才能写入或更新 `knowledge.yaml`；全项目强制或权限类规则还需
+User / Decision Owner 确认。
+
+Test 对显式引用回报 `not_applicable` 时，说明 Coordinator 的选择需要纠正。该引用
+仍在 `knowledgeRefs` 中就不能把任务标为 `verified`；Coordinator 应记录原因、移除
+误选引用并重新校验，或继续补充验证。
+
+知识中的 `verification.ref` 只能引用
+`knowledge.yaml.verificationRegistry` 里已审查的仓库内相对 path 和结构化 args，
+不能从知识正文拼接或执行自由 shell。Developer/Test 只把 `verification.ref` 交给
+`<ack-skill-dir>/scripts/run_verification.py`；该入口从项目根目录逐段安全打开检查
+文件，拒绝 symlink 路径，并从匿名稳定快照执行。关键约束应下沉为测试、lint、CI
+或正式规范。检查进程从固定的项目根 fd cwd 运行；检查脚本应使用 cwd 或
+`ACK_PROJECT_ROOT` 定位资源。后者是 fd 路径，原始展示路径只在
+`ACK_PROJECT_ROOT_DISPLAY` 中用于日志；不能依赖 `$0` / `__file__` 的目录。
 
 ---
 
@@ -84,7 +134,10 @@ orca terminal create --worktree path:<new> --command "cursor-agent --yolo --mode
 | 要保持基线分支干净 | 新 worktree（feature 分支）|
 | 小改动、追求快 | 当前 worktree |
 
-**任务板（SSOT）只落一处**：无论开几个 worktree，`tasks.yaml` 只认一个权威副本（通常在基线/协调所在 worktree），由 Coordinator 单写。不要每个 worktree 各留一份会分叉的任务板。模型固定方式见 `model-routing.md` 与 `orca-adapter.md`。
+**项目状态（SSOT）只落一处**：无论开几个 worktree，`tasks.yaml` 和
+`knowledge.yaml` 都只认一个权威副本（通常在基线/协调所在 worktree），由
+Coordinator 单写。不要每个 worktree 各留一份会分叉的项目状态。模型固定方式见
+`model-routing.md` 与 `orca-adapter.md`。
 
 ---
 
@@ -93,14 +146,17 @@ orca terminal create --worktree path:<new> --command "cursor-agent --yolo --mode
 没有编排工具时，闭环不变，只是 `dispatch` / `wait` 由人工承担：
 
 1. Coordinator 在 `tasks.yaml` 写好任务和验收信号。
-2. 用 `prompt-templates.md` §1 的初始派发模板生成 prompt，手动发给 Developer（另一个会话/终端/人）。
+2. 从 `knowledge.yaml` 推荐相关 active 知识，Coordinator 确认固定 revision 的
+   `knowledgeRefs`；用 `prompt-templates.md` §1 的初始派发模板生成 prompt，
+   手动发给 Developer（另一个会话/终端/人）。
 3. Developer 完成后按 worker_done 模板回报。
 4. Coordinator 写回 `fixed_by_dev`，用 `prompt-templates.md` §3 的复测派发模板把任务发给 Test。
-5. Test 独立复测后按复测报告模板回报证据。
+5. Test 独立复测后按复测报告模板回报证据和 `knowledgeChecks`。
 6. Coordinator 做终检并回写 `tasks.yaml`：通过 `verified`，不过 `failed_retest`。
 7. 失败则用「复测失败再派发模板」重新发给 Developer，最多累计三轮。
 
-手动模式下同样遵守：worker_done / 复测报告都不等于最终结论、只有 Coordinator 写 `tasks.yaml`、三轮失败留档。
+手动模式下同样遵守：worker_done / 复测报告都不等于最终结论、只有 Coordinator
+写 `tasks.yaml` 和 `knowledge.yaml`、三轮失败留档。
 
 ---
 
@@ -125,7 +181,9 @@ actual:
 snapshot evidence:
 ```
 
-Test 只回传证据，不写 `tasks.yaml`；由 Coordinator 落盘。
+Test 只回传证据，不写 `tasks.yaml` 或 `knowledge.yaml`；由 Coordinator 落盘。
+每条适用的显式 `knowledgeRef` 还应报告 `passed`、`failed` 或
+`not_applicable` 及证据。
 
 ---
 
@@ -134,6 +192,8 @@ Test 只回传证据，不写 `tasks.yaml`；由 Coordinator 落盘。
 Test 报通过后，Coordinator 不重测，而是做一次读证据的终检：
 
 - Test 证据是否覆盖了任务的**每一条**验收信号（见 `optimization-method.md` §1）。
+- 当前任务显式 `knowledgeRefs` 的必需 `knowledgeChecks` 是否全部覆盖，检查引用
+  是否能解析到项目已审查的入口。
 - 结果是否符合任务的**原始意图**，而不只是通过了字面文案。
 - 运行环境是否对齐（见下方「服务与 worktree 对齐」）。
 

skills/ack/references/init-new-project.md

@@ -11,8 +11,10 @@
 2. ACK Skill 已全局安装或安装到当前项目。
 3. `skiff` 命令可用。
 
-不要覆盖已有的 `docs/ack/project.md`、`docs/ack/tasks.yaml`、`AGENTS.md` 或其它
-Agent 指令文件。不要把 token、`.env` 内容或其它私有配置写入 ACK 项目状态。
+不要覆盖已有的 `docs/ack/project.md`、`docs/ack/tasks.yaml`、
+`docs/ack/knowledge.yaml`、`AGENTS.md` 或其它 Agent 指令文件。ACK 不会自动
+修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。不要把 token、`.env`
+内容或其它私有配置写入 ACK 项目状态。
 
 ## 初始化
 
@@ -33,12 +35,23 @@ skiff init ack --project <project-root>
 ```text
 docs/ack/
 ├── project.md
-└── tasks.yaml
+├── tasks.yaml
+└── knowledge.yaml
 ```
 
 如果任一目标文件已经存在，命令会拒绝覆盖。初始化过程不会创建 `kit`、
 `framework` 或其它指向 Skill 的软链接。
 
+### 旧项目补充知识库
+
+旧项目已经有 `project.md` 和 `tasks.yaml`、但没有 `knowledge.yaml` 时，不要重跑
+`skiff init ack`。先检查现有文件并向用户报告缺失项；用户授权后，只从
+`templates/knowledge.template.yaml` 生成 `docs/ack/knowledge.yaml`，替换项目名和
+当前时间，保留 `entries: []`。如果现有任务板缺少
+`project.knowledgeFile`，同一次授权只补
+`knowledgeFile: docs/ack/knowledge.yaml`，不改写其它项目状态。生成后运行任务板、
+知识库和跨文件引用校验。
+
 ## 完善项目覆盖层
 
 编辑 `docs/ack/project.md`，填入：
@@ -57,35 +70,55 @@ docs/ack/
 
 - `ackVersion` 使用 ACK Skill 的 `VERSION`。
 - `updatedAt` 使用当前带时区时间。
-- `project.name`、`repoPath`、`devWorktree` 和 `overlayFile` 使用真实值。
+- `project.name`、`repoPath`、`devWorktree`、`overlayFile` 和 `knowledgeFile` 使用
+  真实值。
 - 非服务项目的 `baseUrl` 写为 `n/a`。
 - 没有真实任务时使用 `tasks: []`，不要保留或虚构示例任务。
 
 每个真实任务的验收必须是可观测信号，例如可见文本、API 状态和字段，或明确的交互
 结果；不要只写“功能正常”。
 
+## 初始化项目知识
+
+新项目的 `docs/ack/knowledge.yaml` 保持 `verificationRegistry: {}` 与
+`entries: []`。不要从聊天、README、issue 或单次失败中猜测并激活知识。
+
+项目运行 ACK 后，Developer 和 Test 可以通过回报提名 `knowledgeCandidates`；
+candidate 留在任务证据中，不会被派发。只有 Test 独立验证且 Coordinator gate
+通过后，Coordinator 才能把它写成 `active` 条目。全项目范围的强制或权限类规则
+还需要 User / Decision Owner 确认。
+
+知识条目只引用项目已审查的 `verification.ref`。对应入口保存在
+`knowledge.yaml.verificationRegistry`，只允许仓库内相对 path 和结构化 args，
+不保存或自动执行自由 shell 命令。需要执行时只把 registry ID 交给
+`<ack-skill-dir>/scripts/run_verification.py`，不直接运行 path/args。关键约束应
+最终下沉为测试、lint、CI 或正式规范。
+
 ## 校验
 
 Agent 从当前 `SKILL.md` 解析 ACK Skill 目录后运行：
 
 ```bash
 python3 <ack-skill-dir>/scripts/validate_tasks.py docs/ack/tasks.yaml
+python3 <ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml --tasks docs/ack/tasks.yaml
 ```
 
 同时确认：
 
-- `project.md` 和 `tasks.yaml` 没有未替换的 `<...>` 占位符。
+- `project.md`、`tasks.yaml` 和 `knowledge.yaml` 没有未替换的 `<...>` 占位符。
 - `project.overlayFile` 指向真实文件。
+- `project.knowledgeFile` 指向 `docs/ack/knowledge.yaml`。
 - Developer 与 Test 的验证命令可执行。
 - 网站或 API 项目写清服务启动、重启和 Base URL。
+- 任务中的固定 revision `knowledgeRefs` 都能解析，非 `active` 条目没有被派发。
 
 ## 初始化报告
 
 完成后报告：
 
-- 创建或确认的两个项目文件。
+- 创建或确认的三个项目文件。
 - 检测到的技术栈和验证命令。
-- 任务板校验结果。
+- 任务板和项目知识校验结果。
 - 仍需用户补充的值。
 
 只有结构校验通过且必填项目事实完整时才称“初始化完成”；否则称“部分完成”，并列出

skills/ack/references/kickoff.md

@@ -16,11 +16,15 @@
 我要做一个新需求：<一句话需求>。
 你作为 ack 的 Coordinator(PM)，按 ACK Skill 的 references 规范执行：
 
-1. 先读 docs/ack/project.md、references/roles-and-permissions.md、closed-loop.md、optimization-method.md。
+1. 先读 docs/ack/project.md、docs/ack/tasks.yaml，校验 docs/ack/knowledge.yaml 并
+   用 `scripts/select_knowledge.py` 只读取当前任务相关的 active 条目，再读
+   references/roles-and-permissions.md、closed-loop.md、optimization-method.md。
 2. 写产品文档到 docs/（PRD / 交互 / 验收），把需求拆成任务，每个任务的验收写成可观测信号（可见文本 / API 结果 / 交互结果）。
-3. 把任务写进 docs/ack/tasks.yaml（只有你写），跑 validate 校验结构。
-4. 先把「产品文档 + 任务拆分 + 验收信号」给我确认，不要急着派发。
-5. 我确认后，按 ack 闭环循环：先按 docs/ack/project.md 校验 Developer/Test worker 启动命令，
+3. 按任务 scope 从 knowledge.yaml 推荐 active 知识，确认后把固定 revision 的
+   knowledgeRefs 写入任务；不要派发 candidate 或全量知识库。
+4. 把任务写进 docs/ack/tasks.yaml（只有你写），校验 tasks.yaml 和 knowledge.yaml。
+5. 先把「产品文档 + 任务拆分 + 验收信号 + 适用知识引用」给我确认，不要急着派发。
+6. 我确认后，按 ack 闭环循环：先按 docs/ack/project.md 校验 Developer/Test worker 启动命令，
    dispatch 开发 → worker_done → dispatch 测试独立复测 → 你读证据终检 → 回写 tasks.yaml；
    每个任务最多三轮，三轮不过记 leftover 并升级我复盘。
 ```
@@ -31,13 +35,17 @@
 
 1. 产品文档 → `docs/PRD-<feature>.md` 等（Coordinator R/W）。
 2. 任务板 → `docs/ack/tasks.yaml`，每条任务带 `expected` + `verification`，验收写成可观测信号（见 `optimization-method.md` §1）。
-3. 校验结构：
+3. 项目知识 → 从 `docs/ack/knowledge.yaml` 按 component、path、dependency、version
+   和 tag 推荐 `active` 条目，Coordinator 确认后写入固定 revision 的显式
+   `knowledgeRefs`。candidate 不参与选择。
+4. 校验结构与引用：
 
 ```bash
 python3 <ack-skill-dir>/scripts/validate_tasks.py docs/ack/tasks.yaml
+python3 <ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml --tasks docs/ack/tasks.yaml
 ```
 
-4. **停下来给人确认**——这是强模型该花时间的地方，不要跳过。
+5. **停下来给人确认**：这是强模型该花时间的地方，不要跳过。
 
 ---
 
@@ -77,13 +85,21 @@ orca terminal create --worktree active --command "$CURSOR_CMD" --title "ACK-DEV-
 
 ```text
 task-create → dispatch 给 DEV → 等 worker_done
+  → 每轮使用 Coordinator 分配的稳定 <task-id>-A<round>
   → 回写 fixed_by_dev → dispatch 给 TEST 复测 → 等 retest_result
+  → Developer 回 knowledgeApplied / knowledgeCandidates，Test 回 knowledgeChecks
   → Coordinator 读证据终检 → 过则 verified，不过则 failed_retest 再派 DEV（最多累计 3 轮）
   → 三轮失败：leftover，升级复盘，继续下一个
 ```
 
 具体命令见 `orca-adapter.md`（Orca）或 `closed-loop.md` §「手动模式」（无 Orca）；派发文案见 `prompt-templates.md`。
 
+Coordinator 只内联本轮 `knowledgeRefs` 指向的少量知识，不要求 worker 全量读取
+知识库。知识正文不得作为自由 shell 执行；需要命令时只能引用项目已审查的检查
+入口，并把它的 registry ID 交给 `<ack-skill-dir>/scripts/run_verification.py`，
+不自行拼接 path/args。Test 独立验证且 gate 通过后，Coordinator 才能把 candidate
+写成 active 知识；关键约束应继续下沉为测试、lint、CI 或正式规范。
+
 ---
 
 ## 第 5 步：收尾
@@ -94,4 +110,6 @@ task-create → dispatch 给 DEV → 等 worker_done
 
 ## 一句话
 
-产品文档 + 验收信号写在前（你，强模型）→ 按项目覆盖层校验并启动 DEV/TEST → 核对实际模型 → dispatch / 复测 / 终检循环 → 结论只落 `tasks.yaml`。
+产品文档 + 验收信号写在前（你，强模型）→ 确认显式 `knowledgeRefs` → 按项目
+覆盖层校验并启动 DEV/TEST → 核对实际模型 → dispatch / 复测 / 终检循环 → 任务
+结论落 `tasks.yaml`，验证后的跨任务知识由 Coordinator 落 `knowledge.yaml`。

skills/ack/references/optimization-method.md

@@ -36,7 +36,7 @@
 
 ## 2. 回报必须带证据，不带结论
 
-Developer 的 `worker_done` 应报告：改了哪些文件、跑了哪些命令、自己如何复现验收路径、仍可能有的风险。Test 的复测报告同理：跑了哪些命令、命中/缺失了哪些验收信号、实际观察到什么、证据（snapshot / API 结果）。两者的"结论"都不作数，只有 Coordinator 落盘的 `tasks.yaml` 才是事实。
+Developer 的 `worker_done` 应报告：改了哪些文件、跑了哪些命令、自己如何复现验收路径、仍可能有的风险。Test 的复测报告同理：跑了哪些命令、命中/缺失了哪些验收信号、实际观察到什么、证据（snapshot / API 结果）。两者的"结论"都不作数；任务结论只有 Coordinator 落盘到 `tasks.yaml` 才算数，跨任务知识只有 Coordinator 落盘到 `knowledge.yaml` 才会生效。
 
 不要写：
 
@@ -138,7 +138,41 @@ one dispatch = one bug = one acceptance path
 
 ---
 
-## 9. 结束条件
+## 9. 让经验成为有证据、会过期的知识护栏
+
+项目特有、跨任务复用且会改变后续开发或验证行为的经验，可以提名到项目知识护栏。
+不要把全部对话、日志或单次猜测自动保存成“记忆”。
+
+```text
+Developer / Test 当前任务观测
+  -> knowledgeCandidates（只留在任务证据）
+  -> Test 独立验证 + Coordinator gate
+  -> Coordinator 写入 active knowledge
+  -> stale
+  -> superseded / archived
+```
+
+`prepare(task)` 时只按 component、path、dependency、version 和 tag 推荐相关
+`active` 条目；自动匹配只负责推荐，Coordinator 确认固定 revision 的显式
+`knowledgeRefs` 才是本轮权威上下文。每轮只派发命中的少量条目，不全量注入知识库。
+
+Developer 回报实际采用的 `knowledgeApplied` 和带当前观测证据的
+`knowledgeCandidates`。Test 对本轮显式引用回报 `knowledgeChecks`，并用独立观测
+确认或否定 candidate。同一 Agent 不能把自己读到的旧知识复述成新证据，避免错误
+知识自我强化。
+
+知识中的验证只能引用 `knowledge.yaml.verificationRegistry` 中已经审查的仓库内
+相对 path 和结构化 args，不能把正文或选择器输出拼接成自由 shell 执行。实际运行
+只把 registry ID 交给 `<ack-skill-dir>/scripts/run_verification.py`。安全、正确性
+和兼容性等关键约束一旦稳定，应下沉为测试、lint、CI 或正式规范；知识项继续解释
+触发条件、原因与证据，不替代可执行控制。
+
+依赖、配置、路径或版本变化后应重新审查相关知识。临时 workaround 必须有失效或
+移除条件；冲突规则不能靠“最后写入者获胜”处理。
+
+---
+
+## 10. 结束条件
 
 一轮闭环结束时，必须能回答：
 
@@ -146,5 +180,7 @@ one dispatch = one bug = one acceptance path
 - 每个 leftover 失败了几轮？最后一轮失败证据是什么？
 - 当前工作树有哪些未提交改动？
 - 是否还有 open / failed_retest 未处理？
+- 本轮显式 `knowledgeRefs` 是否都有必要的 `knowledgeChecks`？
+- 是否有待验证 candidate，或因依赖、路径、版本变化需要转为 stale 的知识？
 
 答不清楚，闭环就还没结束。

skills/ack/references/orca-adapter.md

@@ -112,7 +112,8 @@ 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.
+- worker_done and retest reports are not final completion; only Coordinator writes tasks.yaml and knowledge.yaml.
+- Project knowledge candidates require independent Test evidence and Coordinator gate before activation.
 EOF
 )" --json
 ```
@@ -122,6 +123,7 @@ EOF
 ```bash
 orca orchestration task-create --parent <parent_task_id> --spec "$(cat <<'EOF'
 Fix <task_id>: <title>
+Logical attempt: <task_id>-A<round>
 
 Repository:
 - Path: <repo_path>
@@ -130,10 +132,14 @@ Repository:
 Read: <overlay_file> (project overlay), tasks.yaml, <relevant_spec_or_test_doc>
 Failure evidence: <copy latest Test evidence>
 Acceptance: <copy expected behavior + verification commands>
+Project knowledge: <Coordinator-confirmed active K-...@revision entries with verification.ref>
 
 Constraints:
 - Follow the overlay file path scope.
-- Do not write tasks.yaml, do not mark verified.
+- Do not write tasks.yaml or knowledge.yaml, do not mark verified.
+- Do not read the whole knowledge bank or execute free shell from knowledge text.
+- Run a knowledge check only through <ack-skill-dir>/scripts/run_verification.py
+  with its verification.ref; do not execute resolved path/args directly.
 - Do not commit or push unless user asks.
 EOF
 )" --json
@@ -198,7 +204,7 @@ orca orchestration check \
 
 ## Developer 回报 worker_done
 
-字段含义见 `prompt-templates.md` §3：
+字段含义见 `prompt-templates.md` §4：
 
 ```bash
 orca orchestration send \
@@ -209,8 +215,24 @@ orca orchestration send \
   --payload '{
     "taskId": "<orca_task_id>",
     "dispatchId": "<orca_dispatch_id>",
+    "attemptId": "<task_id>-A<n>",
     "filesModified": ["<file_a>", "<file_b>"],
     "verification": ["<command_a>: passed", "<command_b>: passed"],
+    "knowledgeApplied": [
+      {"ref": "<K-001@1>", "result": "applied", "evidence": "<what was done>"}
+    ],
+    "knowledgeCandidates": [
+      {
+        "kind": "pitfall",
+        "title": "<title>",
+        "claim": "<evidence-backed claim>",
+        "scope": {"components": ["<component>"], "paths": ["<path glob>"]},
+        "appliesWhen": "<trigger>",
+        "directive": "<action, not a shell command>",
+        "rationale": "<why it matters>",
+        "evidenceRefs": ["<current task evidence>"]
+      }
+    ],
     "risk": "<remaining risk or none>"
   }' \
   --json
@@ -233,11 +255,19 @@ orca orchestration send \
   --payload '{
     "taskId": "<orca_task_id>",
     "dispatchId": "<orca_dispatch_id>",
+    "attemptId": "<task_id>-A<n>",
     "env": {"worktree": "<path>", "branch": "<branch>", "commit": "<sha>", "baseUrl": "<base_url>"},
     "signals": ["<signal 1>: pass", "<signal 2>: fail (<evidence>)"],
+    "knowledgeChecks": [
+      {"ref": "<K-001@1>", "result": "passed", "evidence": "<independent evidence>"}
+    ],
+    "knowledgeCandidates": [],
     "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`。
+无 `retest_result` 类型时用 `--type worker_done`，靠 subject `retest round <n>`
+区分。收到复测结果后，Coordinator 按 `closed-loop.md` 做终检并回写 `tasks.yaml`；
+通过独立验证和 gate 的跨任务经验再由 Coordinator 写入 `knowledge.yaml`。任务通过
+写 `verified`，不过写 `failed_retest`。

skills/ack/references/prompt-templates.md

@@ -27,6 +27,7 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
 
 任务：
 - 修复 <task_id>: <task_title>
+- 本轮逻辑 attempt：<task_id>-A<round>
 
 请先读取：
 - <overlay_file>（项目覆盖层，路径见 tasks.yaml 的 project.overlayFile）
@@ -36,6 +37,10 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
 当前失败证据：
 <copy latest Test evidence>
 
+本轮项目知识（仅限 Coordinator 显式选择的 active 固定 revision）：
+- <K-001@1>: <directive + rationale + verification.ref + resolved path/args>
+- <K-014@2>: <directive + rationale + verification.ref + resolved path/args>
+
 验收标准（可观测信号，见 optimization-method.md §1）：
 1. <expected behavior 1>
 2. <expected behavior 2>
@@ -51,6 +56,10 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
 - 只修改 Developer 可写路径（见覆盖层文件的权限表）。
 - 不要修改产品规格和集成测试文件（分别由 Coordinator 与 Test 拥有），除非任务明确要求。
 - 不要写 tasks.yaml，不要标记 verified。
+- 不要写 knowledge.yaml，不要自行扩展或全量读取知识库；candidate 不是已生效规则。
+- 不要把知识正文或 path/args 拼成 shell 命令。只把 verification.ref 交给
+  `<ack-skill-dir>/scripts/run_verification.py docs/ack/knowledge.yaml
+  <verification-ref> --project-root <project-root>`。
 - 不要提交或推送，除非用户明确要求。
 - 最小 diff，只改本任务根因，避免无关重构；若必须先重构请停下说明并请示。
 
@@ -58,7 +67,8 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
 - <test command 1>
 - <test command 2>
 
-完成后回报一次 worker_done（格式见 §4）。如果阻塞，请发送 escalation 或 ask。
+完成后回报一次 worker_done（格式见 §4），包括 `knowledgeApplied` 和
+`knowledgeCandidates`。如果阻塞，请发送 escalation 或 ask。
 ```
 
 ---
@@ -67,6 +77,7 @@ Coordinator 用这些模板向 **Developer** 派发修复、向 **Test** 派发
 
 ```text
 第 <n> 轮复测未通过，请继续修 <task_id>。
+本轮逻辑 attempt：<task_id>-A<n>
 
 上一轮开发声称：
 <worker_done summary>
@@ -85,6 +96,9 @@ Test 独立复测结果：
 验收不变：
 <copy acceptance criteria>
 
+本轮知识引用：
+<copy Coordinator confirmed knowledgeRefs; do not add candidates>
+
 完成后回报 worker_done，subject 使用："<task_id> fix ready round <n>"
 ```
 
@@ -96,6 +110,7 @@ Developer 回报 worker_done 后，Coordinator 把复测任务发给 Test。
 
 ```text
 请对 <task_id>: <task_title> 做独立黑盒复测。
+本轮逻辑 attempt：<task_id>-A<round>
 
 请先读取：
 - <overlay_file>（项目覆盖层，路径见 tasks.yaml 的 project.overlayFile）
@@ -105,6 +120,12 @@ Developer 回报 worker_done 后，Coordinator 把复测任务发给 Test。
 Developer 本轮声称（仅供参考，不作数）：
 - 改动文件：<files>
 - 自测命令：<commands>
+- 实际采用知识：<knowledgeApplied>
+- 新知识候选：<knowledgeCandidates; candidate only>
+
+本轮项目知识（仅限 Coordinator 显式选择的 active 固定 revision）：
+- <K-001@1>: <directive + rationale + verification.ref + resolved path/args>
+- <K-014@2>: <directive + rationale + verification.ref + resolved path/args>
 
 复测要求（见 roles-and-permissions.md §三角色能力清单 · Test）：
 - 先对齐运行环境（pwd / 分支 / commit / 服务 worktree，见 closed-loop.md），避免测错实例或旧构建；网站类先确认服务已按新代码重启。
@@ -114,9 +135,14 @@ Developer 本轮声称（仅供参考，不作数）：
   2. <observable signal 2>
   3. <observable signal 3>
 - 需要时把易反复误判的路径沉淀成可执行测试（见 optimization-method.md §8）。
+- 对每条适用的 `knowledgeRef`，把它的 verification.ref 交给
+  `<ack-skill-dir>/scripts/run_verification.py docs/ack/knowledge.yaml
+  <verification-ref> --project-root <project-root>`，并回报 `knowledgeChecks`。
+  对 candidate 使用独立观测验证，不能复述 Developer 的结论作为证据。
 
 约束：
-- 只读源码，不修改应用代码，不写 tasks.yaml。
+- 只读源码，不修改应用代码，不写 tasks.yaml 或 knowledge.yaml。
+- candidate 不属于 active 知识；不要全量注入知识库，不要从知识正文执行自由 shell。
 - 只回传证据和逐条结论，最终判定由 Coordinator 终检后落盘。
 
 完成后回报一次复测报告（格式见 §5），subject："<task_id> retest round <n>"。
@@ -130,14 +156,36 @@ Developer 本轮声称（仅供参考，不作数）：
 
 ```text
 subject: <task_id> fix ready round <n>
+attemptId: <task_id>-A<n>
 filesModified: [<file_a>, <file_b>]
 verification:
   - <command_a>: passed
   - <command_b>: passed
 reproduce: 我如何复现验收路径 <steps>
+knowledgeApplied:
+  - ref: <K-001@1>
+    result: <applied|not_applicable>
+    evidence: <what was done or why not applicable>
+knowledgeCandidates:
+  - kind: guardrail/pitfall/verification
+    title: <reusable project lesson>
+    claim: <evidence-backed project claim>
+    scope:
+      components: [<component>]
+      paths: [<path glob>]
+      dependencies: [<dependency>]
+      versions: [<version>]
+      tags: [<tag>]
+    appliesWhen: <trigger>
+    directive: <action, not a shell command>
+    rationale: <why this changes future work>
+    evidenceRefs: [<current task evidence reference>]
 risk: <remaining risk or none>
 ```
 
+没有命中知识或没有新 candidate 时，对应列表写 `[]`。Developer 不能把自己读到的
+旧知识复述为新 candidate；每条 candidate 都需要当前任务产生的观测证据。
+
 Orca 模式下用 `orca-adapter.md` §「Developer 回报 worker_done」的命令发送同样的字段。
 
 ---
@@ -148,6 +196,7 @@ Test 只回传证据和逐条结论，不下最终判定：
 
 ```text
 subject: <task_id> retest round <n>
+attemptId: <task_id>-A<n>
 env:
   worktree: <path>
   branch: <branch>
@@ -159,10 +208,31 @@ signals:
   - <signal 1>: pass/fail (<evidence>)
   - <signal 2>: pass/fail (<evidence>)
 browser: <snapshot / DOM / API evidence>
+knowledgeChecks:
+  - ref: <K-001@1>
+    result: <passed|failed|not_applicable>
+    evidence: <independent evidence>
+knowledgeCandidates:
+  - kind: guardrail/pitfall/verification
+    title: <new lesson found by Test>
+    claim: <evidence-backed project claim>
+    scope:
+      components: [<component>]
+      paths: [<path glob>]
+      dependencies: [<dependency>]
+      versions: [<version>]
+      tags: [<tag>]
+    appliesWhen: <trigger>
+    directive: <action, not a shell command>
+    rationale: <why this changes future work>
+    evidenceRefs: [<independent evidence reference>]
 conclusion: all-signals-pass / signals-failed
-notes: <observations, suspected cause if failed>
+notes: <observations, suspected cause, and independent candidate validation evidence>
 ```
 
+没有适用项时列表写 `[]`。Test 的知识结论仍只是证据；只有 Coordinator 能写入或
+激活 `knowledge.yaml`。
+
 Orca 模式下用 `orca-adapter.md` §「Test 回报复测结果」的命令发送同样的字段。
 
 ---
@@ -181,6 +251,11 @@ Orca 模式下用 `orca-adapter.md` §「Test 回报复测结果」的命令发
 验证命令：
 - <command>: passed
 
+项目知识：
+- 本轮采用：<knowledgeRefs and checks>
+- 新增或更新：<active/stale/superseded entries written by Coordinator, or none>
+- 待验证 candidate：<remaining candidates or none>
+
 工作树状态：
 - <repo_path>: <git status summary>
 - <dev_worktree>: <git status summary>

skills/ack/references/roles-and-permissions.md

@@ -12,12 +12,12 @@ ACK 默认三个独立 Agent：**Coordinator 只编排、Test 只验证、Develo
 
 | 角色 | 主要职责 | 验证方式 | 不应做的事 |
 |------|----------|----------|------------|
-| Coordinator (PM) | 需求拆解、定验收信号、排优先级、写 `tasks.yaml`、向 Developer/Test 派发、跑三轮闭环、做最终 gate | 读 Test 证据并对齐原始意图（不亲自跑测试） | 修改源码、亲自复测、凭 worker_done 直接标 `verified` |
-| Test | 黑盒复测、回归验证、沉淀可执行测试、产出证据 | 浏览器、API、集成脚本、用户可见行为 | 修改应用源码、修改产品规格、写 `tasks.yaml` |
-| Developer | 实现修复、写单元测试、运行构建和白盒验证 | 单元测试、类型检查、构建、本地运行 | 修改产品规格与集成测试、标记 `verified`、绕过测试声称完成 |
+| 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` 才算数。
+**独立验证权归 Test。** Coordinator 不亲自复测，它读 Test 的证据，并对照任务的原始意图做一次终检（见「完成定义」）。`worker_done` 不等于完成的原则同时适用于 Developer 和 Test：结论只有落到 `tasks.yaml` 才算数。
 
 **模型档位（正交层）。** 三角色默认按成本分层：Coordinator 用强模型，Test 与 Developer 用中低模型，必要时升级。完整档位表与升级规则见 `model-routing.md`。Coordinator 用强模型但不跑测试，这一分工天然省 token 又不破坏「验证者 ≠ 实现者」。
 
@@ -29,7 +29,7 @@ ACK 默认三个独立 Agent：**Coordinator 只编排、Test 只验证、Develo
 
 这些是**通用工程习惯**，不含项目命令与路径；项目差异写在覆盖层文件（默认 `docs/ack/project.md`）。装了外部 skill 的环境可按每个角色末尾的「可选 skills」加速，未装则照本清单执行，不阻塞。
 
-### Coordinator (PM) —— 拆解与终检
+### Coordinator (PM)：拆解与终检
 
 - **Outcome**：把一句话需求变成可执行、验收可观测的任务集，并跑完闭环得到明确结论（verified / leftover）。
 - **Must Do**
@@ -37,38 +37,58 @@ ACK 默认三个独立 Agent：**Coordinator 只编排、Test 只验证、Develo
   - 每个任务写**可观测验收信号**（可见文本 / 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`、把多个无关失败塞进一次派发。
+- **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 —— 实现与白盒验证
+### Developer：实现与白盒验证
 
 - **Outcome**：在授权路径内做出满足验收信号的最小改动，并用白盒证据证明它可复现。
 - **Must Do**
   - 动手前先读覆盖层文件、`tasks.yaml` 对应任务、相关规格；复现失败现象或先写会失败的测试。
+  - 只使用 Coordinator 本轮显式派发的 `active` 知识，按固定 revision 回报
+    `knowledgeApplied`；发现跨任务可复用的项目经验时提交带当前观测证据的
+    `knowledgeCandidates`。
   - 最小 diff，只改一个明确问题的根因，不顺手重构无关代码。
   - 行为变更配单元测试；bug 修复先有一个能复现的失败用例再修。
   - 完成前跑覆盖层里规定的命令（构建 / 单测 / 本地运行），亲自走一遍验收路径。
   - **网站 / 常驻服务**：改完重启服务（或触发热更并确认生效），保证运行实例跑的是新代码，避免 Test 测到旧进程 / 旧构建。
-- **Must Not**：改产品规格与集成测试、写 `tasks.yaml`、标 `verified`、绕过测试声称完成、把 bug 修复扩成大重构（需要就先停下说明并请示）。
-- **Evidence**：改了哪些文件、跑了哪些命令及结果、如何复现验收路径、残留风险。
+- **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 —— 独立黑盒复测
+### 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`、凭 Developer 的 `worker_done` 直接下结论。
-- **Evidence**：运行环境快照、命令结果、每条信号 pass/fail + 证据（snapshot / DOM / API 结果）。
+- **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`（证据先于结论）。
 
@@ -87,7 +107,8 @@ ACK 默认三个独立 Agent：**Coordinator 只编排、Test 只验证、Develo
 | `<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 | 见下方「任务板写入约定」 |
+| `tasks.yaml` | R/W | Read-only | Read-only | 见下方「项目状态写入约定」 |
+| `knowledge.yaml` | R/W | Read-only | Read-only | Coordinator 单写；Developer/Test 通过回报提名或验证 |
 
 ---
 
@@ -126,15 +147,24 @@ failed_retest（累计 3 轮） -> leftover
 
 ---
 
-## 任务板写入约定（并发安全）
+## 项目状态写入约定（并发安全）
 
-`tasks.yaml` 是持久事实源，为避免多 Agent 并发写冲突：
+`tasks.yaml` 是任务事实源，`knowledge.yaml` 是跨任务项目知识事实源。为避免多
+Agent 并发写冲突：
 
-- **只有 Coordinator 写 `tasks.yaml`**。Test 与 Developer 对它都是只读的。
+- **只有 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）
@@ -144,6 +174,8 @@ failed_retest（累计 3 轮） -> leftover
 - Developer 已提供修改文件和白盒验证证据（`worker_done`）。
 - Test 在正确 worktree 和正确服务实例上独立复测通过（对齐检查见 `closed-loop.md`），并产出可观测证据。
 - 相关单元测试、构建、集成或浏览器检查通过。
+- 当前任务显式 `knowledgeRefs` 对应的必需 `knowledgeChecks` 已由 Test 覆盖；
+  未覆盖或检查引用无法解析时不能标记 `verified`。
 - **Coordinator 终检**：读 Test 的证据，确认它满足任务的原始意图与验收信号（不是重测，是审证据 + 对齐意图；避免"过了字面没过意图"）。
 - `tasks.yaml` 中记录了复测证据与 `resolution.verifiedBy`。
 - 用户可见行为符合验收标准。