laily
12e00bd594
Keep pouch naming and .pouch/ack project state, and bring in ACK regression mode, deployer test-environment binding, and manage-release updates from main.
127 lines
7.3 KiB
Markdown
127 lines
7.3 KiB
Markdown
# 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`。
|