.pouch/skills/ack/references/adoption-checklist.md

ACK 接入清单

安装与初始化

• ACK Skill 已全局安装或安装到当前项目。
• 已运行 pouch init ack --project <project-root>。
• .pouch/ack/ 只包含项目自己的 project.md、tasks.yaml、knowledge.yaml、 默认关闭的 delivery.yaml 与空的 regression.yaml。
• 旧项目缺少 knowledge.yaml 时，只补空文件及缺失的 project.knowledgeFile 指针，没有重跑初始化或覆盖其它项目状态。
• 项目中没有 ACK Skill 的复制目录或 kit、framework 软链接。
• tasks.yaml 使用 ackVersion 记录 ACK Skill 版本。

项目覆盖层

• project.md 只保存项目差异，不复制 Skill 的通用规范。
• tasks.yaml 的 project.overlayFile 指向实际覆盖层。
• tasks.yaml 的 project.knowledgeFile 固定为 .pouch/ack/knowledge.yaml。
• 新项目的 project.deliveryFile 固定为 .pouch/ack/delivery.yaml，顶层有 deliveryRuns: []；旧项目未采用交付能力时可无这两项。
• 新项目的 project.regressionFile 固定为 .pouch/ack/regression.yaml，顶层有 regressionRuns: []；旧项目未采用回归能力时可无这两项。
• 技术栈、运行、构建、单测和集成测试命令均来自项目证据。
• Coordinator、Developer、Test 的模型档位和升级规则已明确。
• project.orchestration 使用受支持的 profileVersion，模型都命中项目 allowlist，默认 profile 与角色/档位一致。
• allowedWorktrees 已废弃（v0.19 起），新任务板不配置；worker 默认在 --project-root 工作，其它 worktree 由 launcher 按同 git 仓库且已注册约束放行。
• tasks.yaml 不需要保存 repoPath 或 devWorktree；项目状态从当前 --project-root/.pouch/ack/ 推导，worker 路径由 --worktree 显式指定。

路径权限

• Coordinator 可写规格和任务板。
• Test 可写集成测试与复测记录，但不能改源码。
• Developer 可写源码与单元测试，但不能改规格或黑盒验收。
• 私有配置只读且不提交。
• tasks.yaml 只有 Coordinator 写。
• knowledge.yaml 只有 Coordinator 写；Developer 与 Test 只通过回报提名或验证。
• regression.yaml 只有 Coordinator 写；Test 只通过 regressionCandidates 提名。
• delivery.yaml 只在用户显式维护配置时修改；Developer 与 Test 只读。

任务板

• 已替换项目名、仓库路径、Base URL、worktree 和覆盖层路径。
• 没有真实任务时使用 tasks: []。
• 真实任务的验收是可观测信号。
• 已运行 <ack-skill-dir>/scripts/validate_tasks.py 并通过。

可选交付

• delivery.yaml 首次生成保持 enabled: false，没有根据 README/CI 自动启用。
• 测试环境绑定 deployer（intents.testEnvironment.via: deployer），发版写在 同一份 delivery.yaml 的 intents.release。没有第二份操作文档。未说明的 intent 保持 null。旧 profile ID 字符串已迁移。
• entrypoint 只使用声明式工具 target 或仓库内无 symlink 的可执行脚本；没有 shell、自由 command、凭据值或环境变量值。
• artifact、destination、environment 和 profile 引用均通过 validate_delivery.py --tasks ... --project-root ... 校验。
• 默认 profile 只使用 preview/staging 与非 production 环境，停止在 review_ready。
• stable 发布和 production 部署之前存在 approval 步骤；production 环境有 rollback 入口。
• 本次 ACK 计划明确 profile、task IDs、目标、停止点和审批步骤；配置本身没有 被当作提交、推送、发布或部署授权。
• 每次运行固定 commit/config revision，证据写入 tasks.yaml.deliveryRuns； 失败不会把已验证任务回退为失败。

项目知识

• 新项目没有已验证知识时使用 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 指令文件。

回归

• 新项目 regression.yaml 为 cases: []，没有虚构用例。
• 已运行 validate_regression.py --tasks ... 并通过。
• 任务 verified 后给出新增/更新/退役/无回归四选一，确认后才写入目录。
• 运行回归先走 deployer 测试环境，再派独立 Test；失败不自动开修。

编排

• 已选择 Orca 或手动模式。
• 自动创建只调用 launch_worker.py plan|launch，没有直接拼接 orca terminal create --command 或自由 worker 命令。
• launch 使用刚审阅的 plan.launchFingerprint 作为 --expected-launch-fingerprint；漂移时重新 plan。
• Developer/Test 只使用 read-only 或 workspace-write profile； v0.10 没有 full-access、bypass、YOLO/force 或关闭 sandbox。
• 只考虑同轮、空闲、角色/profile/worktree/启动身份匹配的复用候选；历史消息必须 由受信后端清理并返回新会话身份。任一条件不符或无法确认清理成功时启动 fresh worker；没有把历史 receipt checksum 或 Orca live metadata 当作复用授权。
• launcher receipt 已追加到顶层 workerReceipts，任务分别引用 dispatch.developer 与 dispatch.test；每个引用的 task/role/profile/attempt 都与当前任务、本轮 receipt 完全一致，没有用单一 handle 混淆两个角色。
• 多 worktree 场景只有一个权威 tasks.yaml 和 knowledge.yaml。
• Test 使用的服务来自正确 worktree。

闭环

• worker_done 不直接视为完成。
• Test 独立复测后由 Coordinator 读取证据终检。
• 每轮写入 dispatch.rounds。
• 三轮失败后标记 leftover 并填写原因。
• leftover 不阻塞其它任务。
• Coordinator 标记整轮完成后，已关闭所有只属于 verified 任务的 worker；仍关联 blocked/failed/leftover、未完成任务或未解决环境事件的终端保留且不设 TTL。

首次接入建议选择一个低风险问题跑完整闭环。项目差异写回 .pouch/ack/project.md；通用问题回流到 ACK Skill 的 references/、templates/ 或 scripts/，并更新 VERSION。项目特有、跨任务复用且已经验证的经验才写入 .pouch/ack/knowledge.yaml。