ACK
ACK 是一个显式调用的 Agent Skill，用三种独立角色运行工程协作闭环：
- Coordinator 拆解需求、派发任务并终检。
- Developer 实现并执行白盒验证。
- Test 独立执行黑盒复测。
关键约束是验证者不等于实现者。每个任务最多修复三轮，仍未通过时记录为
leftover，然后继续处理其它任务。
安装
全局安装：
skiff add ack -g
或只安装到当前项目：
skiff add ack
ACK 只在用户显式调用 /ack 或 $ack 时运行。
初始化项目
skiff init ack
skiff init ack --project ~/code/my-app
初始化后，项目只保存自己的 ACK 状态：
docs/ack/
├── project.md
├── tasks.yaml
└── knowledge.yaml
不会在项目中复制或链接 ACK Skill。通用规范、模板和脚本始终从已安装的 Skill 目录读取。
Skill 结构
skills/ack/
├── SKILL.md
├── README.md
├── VERSION
├── references/ # 三角色规范、闭环流程和初始化说明
├── templates/ # project.md、tasks.yaml、knowledge.yaml 模板和 schema
├── examples/ # 完整示例
└── scripts/ # 状态校验、知识选择、安全验证执行与 worker 命令工具
SKILL.md 是 Agent 的工作流入口。references/ 是按需读取的稳定规范；
docs/ack/project.md 只保存当前项目的命令、路径和权限差异；
docs/ack/tasks.yaml 保存当前任务状态；docs/ack/knowledge.yaml 保存跨任务复用、
已经独立验证的项目知识护栏。
检查项目状态
Agent 会从当前 ACK Skill 目录解析校验脚本：
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 可以按当前任务上下文做确定性推荐：
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 的安全执行入口：
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 指令文件。
开始一个需求
初始化完成后可以直接说：
/ack 处理这个需求：<一句话需求>
Coordinator 会先读取项目状态和 references/kickoff.md，生成产品文档、任务拆分与
可观测验收信号；用户确认后才派发实现和复测。
版本
当前 Skill 版本见 VERSION。新项目在 tasks.yaml 中记录 ackVersion。旧项目的
kitVersion 可以继续读取，但建议迁移为 ackVersion。