feat(ack): add project knowledge guardrails

skills/ack/README.md

@@ -37,7 +37,8 @@ skiff init ack --project ~/code/my-app
 ```text
 docs/ack/
 ├── project.md
-└── tasks.yaml
+├── tasks.yaml
+└── knowledge.yaml
 ```
 
 不会在项目中复制或链接 ACK Skill。通用规范、模板和脚本始终从已安装的 Skill
@@ -51,23 +52,69 @@ skills/ack/
 ├── README.md
 ├── VERSION
 ├── references/     # 三角色规范、闭环流程和初始化说明
-├── templates/      # project.md 与 tasks.yaml 模板和 schema
+├── templates/      # project.md、tasks.yaml、knowledge.yaml 模板和 schema
 ├── examples/       # 完整示例
-└── scripts/        # tasks.yaml 与 worker 命令校验器
+└── scripts/        # 状态校验、知识选择、安全验证执行与 worker 命令工具
 ```
 
 `SKILL.md` 是 Agent 的工作流入口。`references/` 是按需读取的稳定规范；
 `docs/ack/project.md` 只保存当前项目的命令、路径和权限差异；
-`docs/ack/tasks.yaml` 保存当前任务状态。
+`docs/ack/tasks.yaml` 保存当前任务状态；`docs/ack/knowledge.yaml` 保存跨任务复用、
+已经独立验证的项目知识护栏。
 
-## 检查任务板
+## 检查项目状态
 
 Agent 会从当前 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
 ```
 
+Coordinator 可以按当前任务上下文做确定性推荐：
+
+```bash
+python3 <ack-skill-dir>/scripts/select_knowledge.py docs/ack/knowledge.yaml \
+  --component web --path web/app.py --tag long-running-service --limit 10
+```
+
+默认 JSON 输出会同时给出固定知识引用和已解析的 `verificationTarget.path/args`；
+选择器只输出数据，不执行检查。`scope.all=true` 的全项目 active 规则优先占用
+`--limit`；如果全项目规则本身超过预算，选择器会显式失败，不会静默漏派。
+
+需要执行知识项引用的检查时，只传 registry ID 给 ACK 的安全执行入口：
+
+```bash
+python3 <ack-skill-dir>/scripts/run_verification.py \
+  docs/ack/knowledge.yaml check-api-contract --project-root <project-root>
+```
+
+该入口会在执行前重新校验知识库，只打开一次项目根目录 fd，再从同一个 fd 逐段以
+`O_NOFOLLOW` 打开知识库和检查文件；检查内容复制到匿名、尽可能 sealed 的稳定
+快照，再以结构化 argv 和 `shell=False` 启动。它不接受临时命令或额外参数。
+选择器输出的 path/args 只用于审阅，不应由 Agent 自行拼接执行。Runner 只读取
+项目内无 symlink 的权威
+`docs/ack/knowledge.yaml`，不接受替代知识文件或放宽后的项目根。检查进程的 cwd
+和 `ACK_PROJECT_ROOT` 都固定到该根 fd；后者是只在检查进程存活期间有效的
+`/proc/self/fd/...` 或 `/dev/fd/...` 路径。原始可读路径另放在
+`ACK_PROJECT_ROOT_DISPLAY`，只能用于日志，不能用于资源访问。Runner 还提供
+`ACK_VERIFICATION_REF` 和 `ACK_VERIFICATION_PATH`；检查脚本必须据此定位资源，
+不能依赖 `$0` 或 `__file__` 所在目录，因为实际执行的是匿名快照。
+
+知识先由 Developer 或 Test 作为 `candidate` 提名，经独立验证和 Coordinator gate
+后才能成为 `active`。Coordinator 按路径、组件、依赖、版本和标签推荐相关知识，
+确认后将固定 revision 的 `knowledgeRefs` 写入任务上下文；每轮只派发命中的少量
+条目，不全量注入知识库。
+
+旧项目只有 `project.md` 和 `tasks.yaml` 时，不要重跑初始化。由 `/ack` 检查现有
+状态，获得用户授权后补一个空的 `knowledge.yaml`；如果任务板尚未声明知识库，
+同时只补 `project.knowledgeFile: docs/ack/knowledge.yaml`，再运行跨文件校验。
+
+只有 Coordinator 写 `tasks.yaml` 和 `knowledge.yaml`。知识正文不能作为自由 shell
+执行；关键约束应继续下沉到测试、lint、CI 或正式规范。ACK 不自动修改项目的
+`AGENTS.md`、`CLAUDE.md` 或其它 Agent 指令文件。
+
 ## 开始一个需求
 
 初始化完成后可以直接说：