laily
af6e139d30
short-ship and long-ship share one ship-id record under .pouch/ship/<id>/. specifier writes PRDs into spec/; delivery-loop appends evidence pointers. Old names stay as deprecation stubs so existing installs keep working.
172 lines
5.0 KiB
Markdown
172 lines
5.0 KiB
Markdown
# Ship 记录契约
|
||
|
||
## 目录
|
||
|
||
- [布局](#布局)
|
||
- [current.yaml](#currentyaml)
|
||
- [short 与 long](#short-与-long)
|
||
- [任务](#任务)
|
||
- [证据指针](#证据指针)
|
||
- [旧 specifier 目录](#旧-specifier-目录)
|
||
|
||
## 布局
|
||
|
||
```text
|
||
.pouch/ship/<ship-id>/
|
||
current.yaml # 总账：kind、状态、stopAt、指针
|
||
spec.md # 短需求说明（short 和 long 都有）
|
||
tasks.yaml # 本 ship 的任务 DAG
|
||
status.md # 给人看的一页摘要
|
||
spec/ # 仅 long：PRD 版本、评审、handoff
|
||
brief.md
|
||
prd-v001.html
|
||
review.yaml
|
||
decisions.yaml
|
||
risks.yaml
|
||
handoff.yaml # 仅 approved 后
|
||
```
|
||
|
||
`status.md` 给人看；Agent 以 `current.yaml` 为准。两份不一致时改 `status.md`。
|
||
|
||
## current.yaml
|
||
|
||
必填：`shipId`、`kind`、`status`、`title`、`spec`、`tasks`、`evidence`。
|
||
`shipId` 必须等于目录名。
|
||
|
||
```yaml
|
||
shipId: add-export-button
|
||
kind: short
|
||
title: 列表页增加导出按钮
|
||
status: in_progress
|
||
stopAt: review_ready
|
||
source:
|
||
kind: user
|
||
ref: null
|
||
parentShipId: null
|
||
childShipIds: []
|
||
spec:
|
||
path: spec.md
|
||
revision: null
|
||
specStatus: null
|
||
prd: null
|
||
approvedRevision: null
|
||
reviews: null
|
||
handoff: null
|
||
tasks:
|
||
path: tasks.yaml
|
||
delivery:
|
||
stopAt: review_ready
|
||
state: change_ready
|
||
evidence:
|
||
testRuns: []
|
||
artifacts: []
|
||
deploys: []
|
||
prs: []
|
||
commits: []
|
||
```
|
||
|
||
`kind`：`short` | `long`。
|
||
|
||
`status`：`draft`、`spec_review`、`approved`、`in_progress`、`blocked`、`done`、`parked`、`superseded`。
|
||
|
||
`delivery.state` 使用 delivery-loop 内部里程碑：`change_ready`、`verified`、
|
||
`pr_opened`、`merged`、`regression_passed`、`artifact_built`、`published`、`deployed`。
|
||
|
||
`source.kind`：`user` | `hunt` | `ack` | `pr` | `feishu`。修 ACK 缺陷时
|
||
`source.kind: ack` 且 `ref` 为缺陷任务 id。
|
||
|
||
## short 与 long
|
||
|
||
同一套字段，厚度不同。
|
||
|
||
| 字段 | short | long |
|
||
| --- | --- | --- |
|
||
| `spec.md` | 四段：要做什么、不做什么、可观察验收、怎么验。有故障证据时加复现和根因 | 同一四段作摘要 |
|
||
| `spec/` | 不要创建 | specifier 写入 PRD、评审、决策、风险、handoff |
|
||
| `spec.revision` 等 | 保持 `null` | 与 PRD 版本同步 |
|
||
| `tasks.yaml` | 恰好 1 条 | DAG；`dependsOn` 指向本文件内 id |
|
||
| 子项 | 无 | 默认是 task。只有该切片有独立 `stopAt` 并单独发布时才晋升为子 ship，写入 `childShipIds` |
|
||
|
||
范围变大时保持同一 `shipId`，把 `kind` 改成 `long`，补 `spec/` 并拆任务。
|
||
|
||
`spec.md` 不要写成 HTML PRD。long 的评审稿是 `spec/prd-vNNN.html`。
|
||
|
||
## 任务
|
||
|
||
`tasks.yaml` 只描述本 ship 的工作项，不是 ACK 缺陷板。
|
||
|
||
```yaml
|
||
shipId: add-export-button
|
||
tasks:
|
||
- id: T-01
|
||
title: 在列表页增加导出按钮
|
||
dependsOn: []
|
||
expected:
|
||
- 登录用户在列表页看到「导出」
|
||
verification:
|
||
- 浏览器打开列表页，按钮可见且可点
|
||
status: open
|
||
stopAt: review_ready
|
||
```
|
||
|
||
允许的任务 `status`：`open`、`in_progress`、`blocked`、`verified`、`merged`、`done`。
|
||
|
||
long 的子任务默认 `stopAt` 为 `pr_opened` 或 `merged`，不要单独打生产 tag 或升级生产。
|
||
父 ship 在依赖任务完成后做集成回归，再按父记录的 `delivery.stopAt` 继续。
|
||
|
||
从 `spec/handoff.yaml` 建任务时复制 `id`、`title`、`dependsOn`、`expected`、
|
||
`verification`，不要写进 `.pouch/ack/tasks.yaml`。
|
||
|
||
## 证据指针
|
||
|
||
不要把 tester 快照、镜像层或 compose 日志复制进 ship 目录。追加指针：
|
||
|
||
```yaml
|
||
evidence:
|
||
testRuns:
|
||
- path: .pouch/tester/runs/20261013T031000Z-smoke-ab12.yaml
|
||
result: pass
|
||
suite: smoke
|
||
artifacts:
|
||
- sha: 0123456789abcdef0123456789abcdef01234567
|
||
digest: sha256:abc
|
||
ref: harbor.example.com/app:1.2.3
|
||
venue: ci
|
||
deploys:
|
||
- env: test
|
||
revision: 0123456789abcdef0123456789abcdef01234567
|
||
health: pass
|
||
prs:
|
||
- url: https://git.example.com/app/-/merge_requests/12
|
||
status: opened
|
||
commits:
|
||
- sha: 0123456789abcdef0123456789abcdef01234567
|
||
role: baseline
|
||
```
|
||
|
||
delivery-loop 阶段与指针：
|
||
|
||
| 阶段 | 至少追加 |
|
||
| --- | --- |
|
||
| `change_ready` | `commits` `role: baseline` |
|
||
| `verified` | `testRuns` |
|
||
| `pr_opened` | `prs` |
|
||
| `merged` | `commits` `role: merged` |
|
||
| `regression_passed` | `testRuns`（回归） |
|
||
| `artifact_built` / `published` | `artifacts` |
|
||
| `deployed` | `deploys` |
|
||
|
||
`path` 相对项目根。文件不存在则校验失败。用 `scripts/append_evidence.py` 追加后立刻
|
||
`validate_ship.py`。
|
||
|
||
## 旧 specifier 目录
|
||
|
||
打开某个 id 时按这个顺序：
|
||
|
||
1. `.pouch/ship/<id>/` 已存在：用它。若同时还留着
|
||
`.pouch/specifier/features/<id>/`，报告旧路径为遗留，不要两处同时写。
|
||
2. 只有 `.pouch/specifier/features/<id>/`：把它移到 `.pouch/ship/<id>/spec/`，按旧
|
||
`current.yaml` 生成 ship `current.yaml`（`kind: long`），用 `brief.md` 补
|
||
`spec.md` 摘要，再校验。
|
||
3. 两处都没有：由入口 skill 调用 `create_ship.py` 新建。
|