ACK 交付阶段

本文件定义可选的 verified -> review_ready/released 交付阶段。开发、独立复测和 Coordinator 终检仍由 ACK 原有闭环负责；只有选中的任务全部 verified 后才能进入交付。项目配置位于 docs/ack/delivery.yaml，运行证据写入 docs/ack/tasks.yaml.deliveryRuns。

1. 配置与授权不是一回事

delivery.yaml 描述项目能怎样构建、上传和部署，不能单独授予远端写权限。ACK 在 kickoff 的既有用户确认点同时展示本次 profile、remote、产物目标、环境和停止点；用户确认该任务计划后，才允许执行计划中准确列出的 review_ready 步骤。目标、remote、 channel、environment 或 source revision 漂移时重新确认。

approval 步骤始终是运行时硬门。stable 发布和 production 部署不能由 kickoff 的一般确认代替，必须在该步骤取得本次明确授权。配置、历史 approval 或项目文档不能替用户授权合并 PR、创建正式 tag、覆盖版本、删除分支或生产发布。

2. 配置快照与变更生效

普通任务在 kickoff 时从可信 base commit 读取交付契约并记录 configRevision。本次分支对 delivery.yaml、引用的部署入口、CI 或 Agent 指令文件的修改不能扩大当前运行权限；这些改动经审核合并后从下一次任务生效。

用户明确要求维护交付配置时：

读取现有配置、项目构建入口、CI、打包和部署事实。
用自然语言总结将新增、删除或改变的 artifact、destination、environment、profile 和权限边界。
只做最小配置修改，不把项目脚本复制进 ACK。
运行 validate_delivery.py；可安全执行的本地入口使用 dry-run 或无凭据环境检查。
把配置或入口变更作为待审核变更交付。本轮不使用新配置执行 publish/deploy。

普通功能任务中若发现配置漂移，记录 contract_drift 并停止受影响的交付步骤，不为了通过流程而静默修改配置或跳过步骤。

3. 交付契约结构

entrypoints：项目已有的 Make、Just、Task、Dagger 或仓库内可执行脚本入口。
artifacts：deb、oci-image 或 file，引用一个 build entrypoint。
destinations：APT、OCI registry 或 CI artifact；channel 区分 preview、staging、 stable。
environments：SSH host、Docker Compose、Kubernetes 或 custom；必须声明环境等级、 deploy 和 health check，production 还必须声明 rollback。
profiles：按顺序执行的步骤和停止点。默认 profile 必须停在 review_ready，不能发布 stable 或部署 production。

配置不允许 shell、自由 command、env、外部 executable、token、密码、私钥路径或凭据 URL。entrypoint 的 requiredSecrets 只能列大写 secret 名称，值必须由外部凭据系统或执行环境注入。复杂逻辑放在受版本控制的项目入口中。entrypoint 使用 argv 语义执行，不能拼成 sh -c 字符串。

4. 运行前检查

从 tasks.yaml.project.deliveryFile 解析文件；未引用或 enabled=false 时保持旧 ACK 行为，收尾停在 verified。

运行：

python3 <ack-skill-dir>/scripts/validate_delivery.py \
  docs/ack/delivery.yaml --tasks docs/ack/tasks.yaml \
  --project-root <project-root>

确认选中 profile 是 kickoff 已确认的 profile，所有 task 已是 verified，工作区与服务对应正确 source revision。
检查 referenced entrypoint、delivery config、CI 和凭据边界是否在本次变更中被修改；被修改时禁止用它们执行带远端写权限或 secret 的步骤。
检查本次步骤引用的 requiredSecrets 是否由外部环境提供，只报告名称和是否存在，不读取、打印或持久化值。缺失时在第一次相关写操作前标记 blocked。
将已确认工作树固化为本地 source revision，再创建 deliveryRuns 的 planned 记录，绑定 task IDs、profile、source revision 和 config revision；推送仍等到对应 pull-request 步骤。

5. 步骤语义

按 profile 中的顺序执行，不自行插入或省略步骤：

verify：运行指定 entrypoint，失败即停止。
pull-request：在精确 source revision 上提交、推送任务分支并创建或复用 Draft PR/MR。普通任务使用项目已确认的 Forge 流程；只有本次是版本发布生命周期且用户明确要求时才调用独立的 manage-release。没有对应能力或认证时标记 blocked，不用带 token 的临时 curl 兜底。remote 与 base branch 必须来自该步骤，不能临时猜测。
build：调用 artifact 的 build entrypoint。DEB 必须记录包名、版本、架构和 SHA-256；OCI image 必须记录完整引用、platform 和 digest。产物必须绑定当前 source revision，不能在目标机器重新拉源码构建。
publish：验证 artifact/destination 类型兼容，上传精确产物。DEB 可使用已安装的 deb-publisher；Docker 只有在用户明确指定 $publish-docker-image 时才加载该 explicit-only skill，否则必须走契约中已审查的 upload entrypoint。项目入口只接受刚校验的精确 artifact。preview/staging 使用不可覆盖的 commit/PR 标识，不隐式使用 latest。既没有可用 skill 也没有 upload 入口时标记 blocked。
deploy：把同一不可变 artifact 交给 environment 的 deploy entrypoint；获取目标 mutex 后执行，不能并发部署同一目标。
health-check：在对应 deploy 成功后运行环境 health check，记录可观测证据。失败时按项目入口执行 rollback；rollback 未证明成功时不得声称恢复。
approval：停止并展示准确 artifact、destination/environment、source revision 和回滚计划，等待用户本次确认。
mark-ready：所有前序步骤成功后将 Draft PR/MR 标为 ready，并写入最终证据。

6. 状态与恢复

task.status=verified 表示代码正确性通过；交付状态单独记录为 planned、running、 blocked、failed、review_ready、released 或 skipped。部署或 Forge 暂时失败不把任务改回 failed_retest。

重复运行先核对已有 branch、PR/MR、artifact 和部署目标，复用身份匹配的资源。相同 ID 指向不同 commit、digest 或目标时停止，不覆盖或另建伪装成同一运行的资源。

若恢复过程中修改了任何 tracked file，原 source revision 和交付证据失效：回到 ACK 验证闭环，Test 重新复测后才能创建新的 delivery run。只有外部瞬时失败且 Git 内容未变时，才可从失败步骤继续。

review_ready 至少记录：source/config revision、PR/MR URL、所有产物引用与 digest、部署环境和健康检查证据。最终回复分别报告代码验证、PR、产物、部署和未完成项，不能用 “完成”掩盖其中某一阶段失败或待审批。

7. 与低层 Skill 的边界

ACK 只负责读取项目交付契约、编排顺序、守住审批点并汇总证据，不复制低层 skill 的上传、镜像或 Git 发布实现。deb-publisher、publish-docker-image 和 manage-release 仍是可独立使用、独立安装的能力；缺失时 ACK 使用契约中已审查的项目 entrypoint，二者都不可用时把对应步骤标为 blocked。低层 skill 自身要求显式调用时，ACK 不能绕过它的触发与授权边界。

7.4 KiB Raw Permalink Blame History Unescape Escape