Ship — 发布与交付

入口/出口

• 入口: 通过 review 的代码
• 出口: docs/features/<name>/05-ship.md + docs/features/<name>/README.md（聚合 README + 事后总结）
• 指向: 完成后进入 reflect-team-retro（可选）
• 输出路径: → ship-workflow-land
• 前置加载: CANON.md + verify-workflow-review/SKILL.md

何时不使用

• 纯配置变更（环境变量、DNS）— 可在监控下直接变更
• 功能尚未通过 review — 必须先完成审查
• 依赖尚未就绪（数据库 migration 未审批、第三方服务未配置）

Iron Law

<HARD-GATE> 没有已验证、可交付、可追溯的发布计划就不上线。software 需要 Staging、Go/No-Go、回滚计划；非软件产物需要导出验证、最终文件路径、版本归档和验收记录。 spec / plan / review 已要求同步的项目级文档，必须在 ship 阶段写入 Documentation Sync 并明确状态；缺少状态不得收口。 </HARD-GATE>

流程

Phase A：预发检查

先读取 spec 的 artifact_type：

• software（默认）→ 加载 ship-infrastructure-deploy，按其 Pre-Launch 检查表逐项执行代码质量、安全、性能、基础设施和文档验证
• document / article / deck / visual → 加载 ship-artifact-export，执行导出、预览、归档和交付检查

验证命令（必须运行）：

npm test && npm run build && npm run lint && npx tsc --noEmit

Phase B：质量门 — Ship Audit Army（发布审计军团）

预发检查通过后，按产物类型并行分派相应 auditor 做发布前专项审计：

Pre-launch checks (Phase A passed)
    │
    ├── agents/ship-security-auditor.md      → 安全审计: OWASP、输入边界、认证授权、数据暴露、依赖
    ├── agents/ship-performance-auditor.md   → 性能审计: 关键路径、N+1查询、内存资源、Bundle影响、退化
    ├── agents/ship-accessibility-auditor.md → 无障碍审计: WCAG合规、屏幕阅读器、表单错误、动态内容
    ├── agents/ship-docs-auditor.md          → 文档审计: CHANGELOG、README、迁移指南、API文档、错误信息
    └── agents/ship-artifact-export-auditor.md → 非 software 导出 QA: source/final 对齐、格式、归档、交付包验证
            │
            ▼
    收集审计结果 → 分级合并 → 修正 → 进入 Staging（Phase B.5）

每个 auditor 输出 Blocking / Important / Suggestion 三级反馈。

阶段技能只分派已被最少触发条件选中的 auditor；未被选中的 auditor 不产出占位反馈。

反馈处理规则：

• Blocking — 必须解决，不上线直到修复
• Important — 强烈必须修复，不修复需在 ship 报告中记录风险接受理由
• Suggestion — 自主判断，采纳后标注来源

最少触发条件：

• 小型变更（单文件、无安全/UI 敏感）→ 可跳过 Audit Army
• software 标准变更 → 至少 security + docs 双审计
• 非 software 标准变更 → 至少 artifact-export + docs 双审计
• 有 UI 变更 → 加 accessibility
• 有性能敏感变更（数据处理、查询、前端 bundle）→ 加 performance
• 用户指定 --full → 当前产物类型相关角色全开

保留向后兼容： 高风险变更也可加载专项审查技能：

• verify-quality-security/SKILL.md — 深度安全专项
• verify-quality-performance/SKILL.md — 深度性能专项
• verify-frontend-accessibility/SKILL.md — 深度无障碍专项

Phase B.5：Staging 验证（仅 software 强制）

software 上线前必须经过 staging 环境验证：

验证步骤：

1. 部署到 staging 环境
2. 运行完整测试套件在 staging 数据上：npm test
3. 手动冒烟测试关键路径（用户注册、登录、核心流程）
4. 验证与下游依赖的集成（API mock 关闭，真实调用）
5. 确认数据 migration 向前兼容
6. 确认回滚脚本可用

staging 不完全 == 不上线。 所有 software 验证必须全部绿色才能进入 Go/No-Go。

非 software 产物在这一阶段改为执行最终交付包验证：

1. 打开 final 文件或预览
2. 检查 source / final / review / ship 记录是否能互相追踪
3. 核对文件名、格式、路径、版本说明
4. 标记 human partner / CI 的最终打开验证结果

Phase C：Go/No-Go 决策

文档化：

## Go/No-Go
- [ ] 阻塞项：无未解决的 Critical 问题
- [ ] 已知风险：[列出]
- [ ] 回滚计划：已准备（强制！）

回滚计划模板：

## 回滚计划

### 触发条件
- 错误率 > 2x 基准
- P95 延迟 > [X]ms

### 回滚步骤
1. 禁用 feature flag（如适用）
   或
1. 部署上一版本：`git revert <commit> && git push`
2. 验证回滚：健康检查、错误监控
3. 沟通：通知团队

### 数据库执行
- Migration [X] 有 rollback
- 新功能插入的数据：[保留 / 清理]

### 回滚时间
- Feature flag: < 1 分钟
- 重部署前一版本: < 5 分钟
- DB rollback: < 15 分钟

Phase D：文档聚合

自动生成 docs/features/<name>/README.md，包含：

• Feature Summary：owner、日期、状态、artifact_type、最终结果、来源目标
• Document Index：00-brainstorm.md 到 07-deploy-report.md 的阶段证据状态
• Timeline：关键阶段日期、证据路径和备注
• Key Decisions：ADR / design / ship 决策索引、理由和当前状态
• Delivery Outcome：已交付、未交付、最终产物、用户可见变化、项目文档和变更统计
• Verification Evidence：review / ship / canary / deploy 门禁证据、结果和 owner
• Residual Risks：剩余风险、影响、owner 和 tracking
• Follow-up Actions：后续动作、owner、due date 和 tracking
• Retro Notes：做得好、应改变、可复用经验

同时检查并记录 Documentation Sync：

• Updated project docs
• Deferred project docs
• CHANGELOG.md updated
• README verified
• 其他 review / plan 标记为必须同步的项目级文档状态

Phase E：发布后闭环（推荐）

发布完成后，必须执行发布后闭环：

• ship-workflow-canary — 金丝雀监控，curl 关键端点比对基线
• ship-workflow-land — 合并 PR、等 CI、验证生产环境
• ship-workflow-doc-sync — 交叉引用变更，同步更新过时文档

分阶段上线策略、Feature Flag 生命周期和推进/回滚阈值详见 ship-infrastructure-deploy。

好/坏示例

好示例：结构化 Go/No-Go + 回滚计划

## Go/No-Go — 任务管理 v2.3
- [x] 阻塞项：无未解决 Critical
- [x] 已知风险：旧版 API 兼容窗口 48h，已准备 fallback 路由
- [x] 回滚计划：feature flag 关闭 < 1min；git revert + redeploy < 5min
- [x] Staging 全绿，冒烟测试通过
- 决策：GO

优点：每项可验证、回滚时间量化、风险显式记录。

坏示例："发了吧"

代码能跑了，周五之前上线吧。出问题再修。

问题：无回滚计划、无 staging 验证、无监控确认、无 Go/No-Go 决策记录。上线后故障无法快速回退。

输出模板

模板起点：

• templates/feature/05-ship.md
• templates/feature/README.md（聚合 README）

# Ship Report — <feature-name>

## 基本信息
- artifact_type: software / document / article / deck / visual
- 版本: <version>
- 发布时间: YYYY-MM-DD HH:MM

## Delivery Scope
- Deliverables:
- Commit / version / artifact path:
- Target users / audience:
- Explicitly out of scope:

## Review Carryover
- Review verdict:
- Blocking remaining:
- Important / deferred risks:
- Review conditions:

## Pre-ship Evidence
| Check | Command / Evidence | Result | Owner |
|-------|--------------------|--------|-------|

## Ship Audit Results
| Audit | Required | Auditor | Result | Blocking findings | Accepted risks |
|-------|----------|---------|--------|-------------------|----------------|

## Final Verification
- software staging:
- smoke / integration verification:
- migration / data compatibility:
- feature flag / kill switch:
- artifact export verification:
- final file / delivery package path:

## Go / No-Go Decision
| Criterion | Required | Status | Evidence |
|-----------|----------|--------|----------|
- Decision: GO / NO-GO
- Decision owner:
- Decision time:

## Rollback / Recovery Plan
- Trigger conditions:
- Recovery steps:
- Data handling:
- Expected recovery time:
- Owner:
- Non-software replacement / re-export plan:

## Documentation Sync
- Updated project docs: [paths or none]
- Deferred project docs: [paths + reasons or none]
- CHANGELOG.md updated: yes / no / n/a
- README verified: yes / no / n/a

## Post-ship Monitoring
- Observation window:
- Health checks / metrics:
- Alert thresholds:
- Monitoring owner:
- First check time:

## Handoff / Archive
- Final artifact / release path:
- Release notes / changelog path:
- Archived evidence path:
- Next command: canary / land / doc-sync / export
- Owner:

聚合 README 必须使用 templates/feature/README.md，并至少保留：

• Feature Summary
• Document Index
• Timeline
• Key Decisions
• Delivery Outcome
• Verification Evidence
• Residual Risks
• Follow-up Actions
• Retro Notes

监控与可观测性

应用级指标

├── 错误率（总数 + 按端点）
├── 响应时间（p50 / p95 / p99）
├── 请求量
├── 活跃用户
└── 关键业务指标（转化率、参与度）

上线后验证

上线后 1 小时内：

1. 健康检查 200
2. 错误监控仪表盘（无新错误类型）
3. 延迟仪表盘（无回归）
4. 手动测试关键用户流程
5. 确认日志正常流动
6. 确认回滚机制就绪

验证失败处理

验证证据

输出或记录必须包含：

• 输入/来源: 读取的 spec、plan、代码、反馈或发布上下文。
• 执行动作: 实际完成的检查、生成、修复、导出或发布步骤。
• 验证结果: 命令、审查结论、产物路径、截图或人工确认。
• 阻塞/回退: 未通过项、回退路径或需要 human partner 决策的问题。

常见说辞

违反字面规则就是违反精神。 没有灰色地带。

红旗

<HARD-GATE> 以下任何一个出现，立即停止发布：

• 没有回滚计划就部署
• 没有监控或错误报告就上线
• 大爆炸式发布（一次性全量，没有 staging）
• Feature flag 没有 owner 或过期时间
• 上线后第一小时无人监控
• 生产环境配置靠记忆而不是代码
• "周五下午了，发了吧"

</HARD-GATE>

验证清单

上线前：

• 预发检查清单完成（全部绿色）
• Delivery Scope 已写清交付物、目标环境和不做范围
• Review Carryover 已带入 04-review.md verdict、条件和残余风险
• Pre-ship Evidence 已记录命令、路径、结果和 owner
• Go/No-Go Decision 已记录 criterion、evidence、owner 和时间
• Feature flag 已配置（如适用）
• Rollback / Recovery Plan 已文档化，包含触发条件、步骤、数据处理和 owner
• Documentation Sync 已完成；必须同步的 project docs 状态明确
• Post-ship Monitoring 已写清观察窗口、指标、阈值和 owner
• Handoff / Archive 已写清最终路径和下一命令
• 聚合 README 已覆盖 00-brainstorm.md 到 07-deploy-report.md 的证据状态
• 聚合 README 已写清剩余风险、后续动作、owner 和 tracking
• 团队已通知上线

上线后：

• 健康检查 200
• 错误率正常
• 延迟正常
• 关键用户流程工作
• 日志正常流动