feat(ack): add project knowledge guardrails

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` 条目没有被派发。
 
 ## 初始化报告
 
 完成后报告：
 
-- 创建或确认的两个项目文件。
+- 创建或确认的三个项目文件。
 - 检测到的技术栈和验证命令。
-- 任务板校验结果。
+- 任务板和项目知识校验结果。
 - 仍需用户补充的值。
 
 只有结构校验通过且必填项目事实完整时才称“初始化完成”；否则称“部分完成”，并列出