# Delivery Loop 状态机

## 状态

```text
change_ready -> verified -> pr_opened -> merged -> regression_passed -> artifact_built -> published -> deployed
```

入口可以从已有状态开始，但不能跳过本次变更所需的验证。内部里程碑可以更细，但项目
Ship 配置使用以下 canonical `stopAt`：

- `develop_verified`：开发阶段验证完成，包含单元测试、新增功能集成测试和静态检查；不等于完整回归。
- `review_ready`：PR/MR 已创建，等待审核。
- `release_ready`：PR 已合并且完整回归通过，映射内部 `regression_passed`；不表示已发布或部署。
- `released`：产物已构建并发布，映射内部 `published`。
- `deployed`：目标环境实际部署完成，映射内部 `deployed`。

旧记录可继续使用 `verified`（`develop_verified` 的别名）和 `validation_ready`
（`release_ready` 的别名）；新记录应使用 canonical 名称。

入口 skill 的自然语言停止点映射如下：

| 用户目标 | Ship stopAt | 必要内部里程碑 |
| --- | --- | --- |
| 只做开发验证 | `develop_verified` | `verified` |
| 发 PR | `review_ready` | `pr_opened`，必要时预览构建/测试 |
| 合并后完整回归 | `release_ready` | `merged`、`regression_passed` |
| 构建并发布产物 | `released` | `merged`、`regression_passed`、`artifact_built`、`published` |
| 实际部署 | `deployed` | `merged`、`regression_passed`、`artifact_built`、`published`、`deployed` |

## 每个阶段的要求

- `change_ready`：记录基线 commit、工作树、目标分支、任务范围和风险。
- `verified`：开发阶段根因或需求验收明确；任务相关单元测试、新增功能集成测试和静态检查通过。
- `pr_opened`：提交说明、测试证据、风险和回滚信息已写入 PR；不能把草稿 PR 当 `review_ready`。
- `merged`：目标分支的合并 commit 已确认，不能只确认源分支 commit。
- `regression_passed`：以合并 commit 执行项目规定的完整回归；失败则回到修复或停止。
  回归 worker 必须先发现项目及其子项目的 tester catalog（使用
  `catalog.py roots --root <project-root>`），逐个测试根执行并记录独立快照；父仓库
  没有 catalog 不能遮蔽有 catalog 的 `app` 子项目。任一发现的测试根未执行或无证据，
  不得把阶段标为 `regression_passed`。还必须执行项目 profile 或
  `.pouch/ack/project.md` 声明的项目原生测试套件，并为每个套件记录命令和结果；任一
  测试面缺少结果时都不能通过回归。
- `artifact_built`：对**合并后的精确 commit SHA** 调用 builder `obtain.sh`。`BUILD_VENUE=ci` 时监听该 SHA 的流水线并 inspect 产物，不在本机重新编译。无流水线、job 失败或 digest 对不上则本阶段失败，不得进入 `published`。项目若声明默认分支不构建，合进 `main` 会 `no_pipeline`：预览推 `dev/*`，正式打 tag。
- `published`：镜像/APK 等外部分发位置可复核，记录 digest 或文件校验和。`venue=ci` 且 CI 已经 push 到 registry 时，obtain 成功即同时满足本阶段，不要再本机 `publish_docker.sh`。
- `deployed`：目标服务运行在预期版本，健康检查和关键路径验证通过。

## 配置和授权

读取项目自己的 delivery 配置，不把命令、主机、秘密复制到通用 skill。优先使用 ACK
的 `delivery.yaml`、builder/deployer/tester 契约和项目版本策略；缺失时停止在最近的安全状态。

生产部署必须同时满足：项目 profile 允许、目标明确、构建来源已固定、回归证据完整、当前
请求覆盖生产部署。没有这些条件时只能报告，而不能用“用户之前说过发布”替代当前授权。

## 证据账本

至少记录：基线和最终 commit、工作树状态、测试命令及结果、黑盒/真机证据、PR/MR URL、
合并 commit、tag、产物路径与摘要、部署节点/服务、健康检查、失败项和回滚指针。

已绑定 ship 记录时，上述证据以指针写入该 ship 的 `current.yaml`，不要另建一份账本。
阶段与字段对应见 ship `references/record.md`。