.pouch/skills/ack/references/delivery.md

ACK 交付阶段

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

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

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

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

2. 配置快照与变更生效

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

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

1. 读取现有配置、项目构建入口、CI、打包和部署事实。
2. 用自然语言总结将新增、删除或改变的 artifact、destination、environment、profile 和权限边界。
3. 只做最小配置修改，不把项目脚本复制进 ACK。
4. 运行 validate_delivery.py；可安全执行的本地入口使用 dry-run 或无凭据环境检查。
5. 把配置或入口变更作为待审核变更交付。本轮不使用新配置执行 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 必须停在 validation_ready 或 review_ready，不能发布 stable 或部署 production。validation_ready profile 必须 至少部署一个 development/staging 环境，并对每个部署目标执行健康检查。

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

3.1 测试环境与发版写在同一份契约

.pouch/ack/delivery.yaml 是测试环境绑定和版本发布的唯一文档。不要另写操作手册， 也不要把其中一项写进 project.md。用户用自然语言说明「怎么布测试环境」或 「怎么发版」时，Coordinator 把两者都维护进这份文件的 intents。

intents:
  testEnvironment:
    via: deployer
    env: test          # 项目 .pouch/deployer/test；尚未说明时为 null
  release: null        # profile ID，或 null

• testEnvironment 绑定 deployer skill 的项目环境目录。用户说「重新布测试环境」 「我要测试」时，ACK 加载 deployer 的 SKILL.md，对 .pouch/deployer/<env> 按服务执行 sync + up 和健康检查。环境目录不存在或 deployer check.py 未通过 时，加载 deployer skill 的「初始化」，不要在 ACK 里复制 compose 命令。派发 Test 复测或跑回归前，若该 intent 已配置且 enabled: true，Coordinator 也先 执行它。不要求当前有 verified 任务。Test 不对这个 intent 发明编译或启动 命令。旧的 profile ID 字符串不再执行，必须迁到 {via: deployer, env: <env>}。 本地进程启动写在 project.md，不算这个 intent。
• release 指向 stopAt: released 的 profile。用户说「发布一个版本」时执行它。 口头「发版」不能代替 stable/production 的 approval 步骤。
• 对应 intent 为 null 或交付未启用：停止，请用户说明怎么做，按「交付配置维护」 写入同一文件后再执行。不猜测 Makefile、镜像仓库或发布通道。
• 用户触发的 intent 运行写入 tasks.yaml.deliveryRuns，intent 填 testEnvironment 或 release，taskIds 可为空。测试环境 run 的 profile 记 deployer-<env>。绑定任务的常规交付 run 不填 intent，仍只能引用 verified 任务。

4. 运行前检查

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

2. 运行：

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

3. 确认选中 profile 是 kickoff 已确认的 profile，所有 task 已是 verified，工作区与 服务对应正确 source revision。

4. 检查 referenced entrypoint、delivery config、CI 和凭据边界是否在本次变更中被 修改；被修改时禁止用它们执行带远端写权限或 secret 的步骤。

5. 检查本次步骤引用的 requiredSecrets 是否由外部环境提供，只报告名称和是否存在， 不读取、打印或持久化值。缺失时在第一次相关写操作前标记 blocked。

6. 将已确认工作树固化为本地 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 与 Docker 均可使用 已安装的 builder；Docker 轨道保持显式触发——只有用户明确点名（builder / 发布镜像） 时才加载，否则必须走契约中已审查的 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、validation_ready、review_ready、released 或 skipped。 validation_ready 表示已把不可变产物部署到开发/测试环境并通过健康检查，可以交给 用户手工验证，不要求存在 PR/MR。部署或 Forge 暂时失败不把 任务改回 failed_retest。

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

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

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

7. 与低层 Skill 的边界

ACK 只负责读取项目交付契约、编排顺序、守住审批点并汇总证据，不复制低层 skill 的 上传、镜像、Git 发布或远程 Compose 实现。builder、manage-release 和 deployer 仍是可独立使用、独立安装的能力。运行测试环境时 ACK 必须加载 deployer skill，不能把 compose/rsync/远程 docker 命令写进 ACK。发版步骤缺失 builder 或 manage-release 时，ACK 使用契约中已审查的项目 entrypoint，二者都不可用 时把对应步骤标为 blocked。低层 skill 自身要求显式调用时，ACK 不能绕过它的 触发与授权边界；ACK 内部调用 deployer 布测试环境是该 skill 的合法调用路径。