feat(ack): add project knowledge guardrails

skills/ack/SKILL.md

@@ -9,8 +9,8 @@ description: >-
 # ACK 项目协作入口
 
 本 Skill 是 ACK 的完整能力包：`references/` 保存通用规范，`templates/` 保存项目
-状态模板，`scripts/` 保存校验工具。目标项目只在 `docs/ack/` 保存 `project.md` 和
-`tasks.yaml`，不要复制或链接 Skill 内容。
+状态模板，`scripts/` 保存校验工具。目标项目只在 `docs/ack/` 保存 `project.md`、
+`tasks.yaml` 和 `knowledge.yaml`，不要复制或链接 Skill 内容。
 
 开始时解析当前 `SKILL.md` 所在目录，记为 `<ack-skill-dir>`。所有通用规范、模板和
 脚本都相对此目录访问，不依赖固定的全局安装路径。
@@ -36,8 +36,12 @@ description: >-
 
    该命令从本 Skill 的 `templates/` 生成项目状态，不会在项目中创建 Skill
    软链接或资源副本。
-3. 如果 `docs/ack` 已存在，不重复初始化、不覆盖文件；转入“检查”，报告缺失项并
-   只补用户授权且能安全确定的内容。
+3. 如果 `docs/ack` 已存在，不重复初始化、不覆盖文件；转入“检查”。旧项目只有
+   `project.md` 与 `tasks.yaml` 时，先报告缺少 `knowledge.yaml`。用户授权后，
+   从 `templates/knowledge.template.yaml` 生成这个缺失文件并替换项目名和时间；若
+   `tasks.yaml` 尚无 `project.knowledgeFile`，同时只补
+   `docs/ack/knowledge.yaml` 这一项。不要重跑 `skiff init`，也不要改写其它已有
+   项目状态。
 4. 读取项目的公开配置和文档，例如 README、语言清单、包管理清单、测试配置与
    CI，确定项目名、技术栈、源码/规格/测试路径及真实可执行命令。
 5. 完善 `docs/ack/project.md`：
@@ -47,15 +51,21 @@ description: >-
    - 只写项目差异，不复制 `references/` 中的通用规范。
 6. 完善 `docs/ack/tasks.yaml` 的项目信息。纯初始化且用户没有提供真实任务时，
    删除模板示例任务并保留 `tasks: []`；不要虚构需求或缺陷。
-7. 更新 `updatedAt`，并运行：
+7. 检查 `docs/ack/knowledge.yaml`。新项目没有已验证的项目经验时保留
+   `verificationRegistry: {}` 与 `entries: []`，不从聊天、README 或单次失败中
+   猜测并激活知识。
+8. 更新 `updatedAt`，并运行：
 
    ```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
    ```
 
-8. 检查 `project.md` 与 `tasks.yaml` 是否仍有 `<...>` 占位符。结构校验通过且
-   必填项目事实完整时才称“初始化完成”；否则称“部分完成”并列出缺失值。
-9. 报告创建的路径、检测到的命令、校验结果和下一步。除非用户明确要求，不提交、
+9. 检查 `project.md`、`tasks.yaml` 与 `knowledge.yaml` 是否仍有 `<...>` 占位符。
+   结构校验通过且必填项目事实完整时才称“初始化完成”；否则称“部分完成”并列出
+   缺失值。
+10. 报告创建的路径、检测到的命令、校验结果和下一步。除非用户明确要求，不提交、
    不推送。
 
 ## 检查
@@ -63,13 +73,18 @@ description: >-
 1. 检查以下路径：
    - `docs/ack/project.md`
    - `docs/ack/tasks.yaml`
+   - `docs/ack/knowledge.yaml`
 2. 读取 `<ack-skill-dir>/VERSION`，对比 `tasks.yaml` 的 `ackVersion`。旧项目只有
-   `ackVersion` 时仍可读取，但建议迁移为 `ackVersion`。
+   `kitVersion` 时仍可读取，但建议迁移为 `ackVersion`。
 3. 查找未替换占位符，并核对项目路径、覆盖层路径、Developer 白盒命令、Test
    黑盒命令和 Base URL。
-4. 使用 `<ack-skill-dir>/scripts/validate_tasks.py` 校验任务板。只报告证据明确的
-   问题，不因可选字段缺失而宣称失败。
-5. 检查不会自动修复或覆盖现有配置；用户明确要求修复后再修改。
+4. 使用 `<ack-skill-dir>/scripts/validate_tasks.py` 校验任务板，使用
+   `<ack-skill-dir>/scripts/validate_knowledge.py docs/ack/knowledge.yaml --tasks
+   docs/ack/tasks.yaml` 校验项目知识和跨文件引用。只报告证据明确的问题，不因可选
+   字段缺失而宣称失败。
+5. 检查知识引用能解析到固定 revision，candidate 仍留在任务证据中，且
+   `stale`、`superseded` 和 `archived` 不会被当作可派发的 `active` 知识。
+6. 检查不会自动修复或覆盖现有配置；用户明确要求修复后再修改。
 
 ## 工作
 
@@ -77,16 +92,28 @@ description: >-
 2. 依次读取：
    - `docs/ack/project.md`
    - `docs/ack/tasks.yaml`
+   - 通过 `<ack-skill-dir>/scripts/select_knowledge.py` 从
+     `docs/ack/knowledge.yaml` 选择的当前任务相关 `active` 条目
    - `<ack-skill-dir>/references/kickoff.md`
    - kickoff 指定且与当前任务相关的 references 文件
 3. 当前会话担任 Coordinator，遵守项目覆盖层中的命令、路径权限、模型路由和
-   worker 复用规则。项目覆盖层优先于通用示例命令。
+   worker 复用规则。项目覆盖层优先于通用示例命令。按 scope 推荐相关 `active`
+   知识，经确认后把固定 revision 的显式 `knowledgeRefs` 写入当前任务上下文；
+   不全量注入知识库。
 4. 新需求先写产品文档、任务拆分与可观测验收信号，更新 `tasks.yaml` 并校验，
    然后交给用户确认；确认前不派发实现。
 5. 用户已确认的任务按 ACK 闭环执行：Developer 实现与白盒验证，Test 独立黑盒
-   复测，Coordinator 读取证据终检并唯一写入 `tasks.yaml`。
-6. 不把 `worker_done` 或 Test 自报成功直接当作完成。每项最多三轮，仍失败则记录
+   复测，Coordinator 读取证据终检并唯一写入 `tasks.yaml`。Developer 回报
+   `knowledgeApplied` 和 `knowledgeCandidates`，Test 回报 `knowledgeChecks`；
+   `candidate` 只有在独立验证和 gate 后才能由 Coordinator 写入或激活。
+6. 执行知识项的 `verification.ref` 时，只调用
+   `<ack-skill-dir>/scripts/run_verification.py docs/ack/knowledge.yaml
+   <verification-ref> --project-root <project-root>`。不要直接执行选择器返回的 path/args，
+   也不要给 runner 注入额外命令或参数。
+7. 不把 `worker_done` 或 Test 自报成功直接当作完成。每项最多三轮，仍失败则记录
    `leftover` 并继续其它任务。
+8. 关键的安全、正确性和兼容性约束应下沉为测试、lint、CI 或正式规范；
+   `knowledge.yaml` 只保存触发条件、原因与证据引用，不能替代可执行控制。
 
 ## 边界
 
@@ -94,5 +121,9 @@ description: >-
 - 不在项目中维护第二份 ACK 通用规范、模板或任务 schema。
 - 不猜测项目命令、服务地址、worker handle 或模型名称。
 - 不覆盖已有 `docs/ack` 文件，不擅自提交、推送、创建终端或新 worktree。
-- 项目只保存 `docs/ack/project.md` 和 `docs/ack/tasks.yaml`；通用资源始终从当前
-  ACK Skill 目录读取。
+- 只有 Coordinator 写 `tasks.yaml` 和 `knowledge.yaml`；Developer 与 Test 只读，
+  只能通过回报提名或验证知识。
+- 不把知识正文或选择器输出拼成 shell；知识检查只能通过 `run_verification.py`
+  按 registry ID 执行。不自动修改 `AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
+- 项目只保存 `docs/ack/project.md`、`docs/ack/tasks.yaml` 和
+  `docs/ack/knowledge.yaml`；通用资源始终从当前 ACK Skill 目录读取。