@chenguangyao/devflow-kit 0.1.43

package/skills/deliver/references/delivery-modes.md

@@ -0,0 +1,299 @@
+# deliver / delivery-modes
+
+4 种 delivery mode 的详细决策树、组织规范建议、边界 case。
+
+---
+
+## 决策矩阵
+
+| 维度 | pr | merge | keep | discard |
+| --- | --- | --- | --- | --- |
+| 有他人 review 需求 | ✅ | ❌ | — | — |
+| 有 CI gate | ✅ | 部分 | — | — |
+| 需要留 PR 讨论 | ✅ | ❌ | — | — |
+| 个人项目 | 可用 | ✅ | — | — |
+| 紧急 hotfix | ✅(加急 review) | ✅(事后补 review) | — | — |
+| 实验 / spike(不上线) | ❌ | ❌ | ✅(临时) | ✅(终态) |
+| 等上游依赖 | — | — | ✅ | — |
+| 需求已取消 | — | — | — | ✅ |
+
+---
+
+## Mode: `pr`(默认,推荐 95% 场景)
+
+### 何时**必须**用 pr
+
+- 团队项目且有 main 分支保护
+- 组织流程要求代码 review
+- 有 CI/CD 门禁(lint / test / security scan)
+- 合规要求保留 discussion 记录
+- L2/L3 change
+
+### pr 的隐含契约
+
+- reviewer 可能要求改 → deliver 不是终点,可能回到 apply
+- CI 必须绿(red CI 的 PR = 没准备好)
+- 提 PR 后保持 **responsive**(24h 内回复评论),不然 PR 越拖越乱
+
+### 什么时候用 Draft PR
+
+- 想让 CI / security scan 跑起来,但还不到 review 阶段
+- 想让团队知道"有这件事在做",但不占 review 时间
+- 多人协作的长 PR
+
+转 Ready for Review:`devflow deliver --mode=pr --mark-ready`(或手动按钮)。
+
+### target 分支的选择
+
+| 策略 | 合到 | 适用 |
+| --- | --- | --- |
+| trunk-based | main | 小团队、CI 强、持续发布 |
+| gitflow | develop | 版本化发布、有 QA 阶段 |
+| release branch | release/x.y | 长周期 release、hotfix 回带 |
+| feature branch 集成 | `feat/xxx-integration` | 超大 feature 由多 change 组成 |
+
+deliver 默认读 `config.delivery.defaultTarget`,项目自己配。
+
+---
+
+## Mode: `merge`
+
+### 何时可用
+
+- **个人项目**:自己 review 自己 commit,无意义走 PR
+- **小团队 trust-based 项目**:如小组内工具仓,已有协议"L1 直接 merge"
+- **hotfix 战时**:产线出事 < 5 分钟决策;事后补 review + 合规记录
+
+### 何时**不要**用
+
+- 团队项目的 feature(即使自己写的)
+- 涉及其他人 code owner 的文件
+- 涉及公共 API / 契约(要让消费方知晓)
+
+### merge 模式的审计
+
+即便 merge 也要记:
+
+```json
+{
+  "delivery": {
+    "mode": "merge",
+    "mergeSha": "abc1234",
+    "mergeAt": "2026-04-24T20:00:00Z",
+    "mergedBy": "@eng-a",
+    "justification": "hotfix: 支付回调重试过多导致 DB 压力上升",
+    "postMergeReview": "PENDING" | "COMPLETED|url"
+  }
+}
+```
+
+`postMergeReview` 是战时 merge 后补 review 的要求,记成 concern,archive 前要完成。
+
+### hotfix 战时流程建议
+
+1. `devflow new <slug> --level=L1 --hotfix`(简化流程)
+2. 快速 apply + verify(smoke + 核心 regression)
+3. `devflow deliver --mode=merge --justification="..."`
+4. 上线验证
+5. 24 小时内补:code review(发给团队 diff)+ retro 记录
+
+---
+
+## Mode: `keep`
+
+### 何时用
+
+- **等上游 PR 合并**:依赖别人的 change,等合了再跟
+- **等 PM 最终确认**:需求还在谈,先把 design 和初步代码准备好
+- **等测试环境资源**:压测排期未到
+- **长假前收尾**:deliver 前发现小问题,但不想急着改
+
+### keep 的超时
+
+默认 14 天:
+
+- 7 天发 notify("该 slug 搁置已 7 天")
+- 14 天提示 "继续 / discard"
+- > 30 天:orchestrator 强提示清理
+
+### keep → pr 恢复
+
+```bash
+devflow deliver --mode=pr     # 接着走 pr,不重跑 verify(除非变了)
+```
+
+如果在 keep 期间代码有变(合并了 main → feature),**重跑 verify 再 deliver**:
+
+```bash
+devflow verify           # 重跑
+devflow deliver --mode=pr
+```
+
+state 会自动检测:`state.verify.ts` 早于最后一次 commit → 提示重跑。
+
+### keep 期间的行为
+
+- 不接受新代码改动(应回 apply 开新 iteration)
+- 可以接受 doc 微调(design 里加个注释、plan 里修 typo)
+- 不能 archive(要 deliver 完才能)
+
+---
+
+## Mode: `discard`
+
+### 何时用
+
+- 需求被明确取消
+- 方案错误,另起炉灶更好(开新 slug,不改旧 slug)
+- spike 完成,结论是"不做"(保留 knowledge 即可)
+- 长期 keep 但上游条件不会到位
+
+### 不要用的场景
+
+- 只是"暂时不做"(用 keep)
+- 想删本地调整重来(用 git reset,不是 discard)
+- 想保留 design 学习(用 `--keep-archive`,默认就是)
+
+### discard 的实际动作
+
+默认(推荐):
+
+```
+devflow/changes/<slug>/ → devflow/archive/discarded/<slug>-<date>/
+               +         DISCARD.md:
+                         - reason
+                         - discarded by
+                         - timestamp
+                         - final state summary
+本地分支 devflow/<slug>/* → 保留(默认)
+worktree → 清
+```
+
+`--purge`(危险):
+
+```
+devflow/changes/<slug>/ → rm -rf
+本地分支 → git branch -D
+worktree → 清
+```
+
+### discard 的审批
+
+discard 是**破坏性**动作,`devflow deliver --mode=discard` 强制:
+
+1. 二次确认(输入 slug)
+2. 若是 L2/L3,要求 `--justification` 至少 50 字
+3. 若关联了 external issue(JIRA / GitLab issue),提示同步关闭或留 comment
+4. 若有 PR 开着,提示先 close PR
+
+---
+
+## 边界 case
+
+### "已经 deliver 了 pr,但 reviewer 要求大改"
+
+- reviewer 说"大改 → 重做":`devflow deliver --mode=keep` 并回 apply / tech-spec
+- reviewer 说"小改":直接 apply 小改 → push 到 feature 分支 → PR 自动更新
+- 根本性改变(比如换方案):建议关掉当前 PR,开新 slug
+
+### "已经 merge 了 pr,但生产出问题"
+
+不是 deliver 的问题,是 rollout 问题。按 design.md 的 rollback 方案走。
+
+deliver 的职责到 "push 到集成轨道" 为止;rollout(灰度 / 金丝雀 / 全量)由 CI/CD 和 ops 负责,devflow-kit 通过 `delivery` 的 post-merge hook 监控并记录。
+
+### "deliver 了 keep,但后面想转 merge"
+
+```bash
+devflow deliver --mode=merge
+# state.delivery.mode 从 keep 变 merge
+```
+
+### "多 slug 并行 deliver,冲突"
+
+orchestrator 层的问题:
+
+- 建议串行 deliver(一个 merge 后再下一个)
+- 或用 feature flag 保护(deliver 不影响实际可见行为)
+- 或用 integration branch(多个 change 合到 integration 再合 main)
+
+### "deliver 完了,发现 spec delta 写错"
+
+不是 deliver 的问题,是 archive 前的问题。deliver 完后,archive 前可以修 delta,archive 会 merge。
+
+---
+
+## 项目规范建议
+
+### 推荐的团队约定(放 `devflow/config/delivery.md`)
+
+```markdown
+# 交付规范
+
+## 默认 mode
+
+- `pr`(任何 change 默认走 PR)
+- 例外:个人 blog repo、文档 typo 修正 → merge
+
+## PR 要求
+
+- 最少 1 个 reviewer(L2)/ 2 个(L3)
+- CI 必须绿
+- self-test 必须完整
+- rollback 方案必写
+
+## 紧急 hotfix
+
+- L1 紧急修复:允许 merge,但 24h 内补 post-merge review
+- 记录到当前需求知识目录的 `knowledge/事故复盘/`
+
+## keep 超时
+
+- 14 天提示
+- 30 天强提示清理
+```
+
+---
+
+## 自动化建议
+
+### 针对大项目的自动化
+
+- PR 模板:`.github/pull_request_template.md` / `.gitlab/merge_request_templates/default.md` 放 deliver 生成的骨架,防止开发偷懒
+- CI 关卡:PR 触发 `devflow verify --check` 和 `devflow doctor` 确认 devflow 文档齐
+- merge hook:merge 后自动跑 `devflow archive`(若无需 rollout 观察期)
+- 定期报告:`devflow metrics` 跑每周报告(L1/L2/L3 分布、平均 delivery 时长、discard 率)
+
+### 针对小项目 / 个人
+
+- 不强制 PR,merge / keep 频用
+- 但 archive 流程保留(sp ec 沉淀价值很大)
+
+---
+
+## mode 和 phase 的关系
+
+```
+verify.status=completed
+   ↓
+deliver (phase=deliver)
+   ↓
+   ├─ mode=pr    → phase=delivering (wait for merge)
+   │              → merged → phase=archive_ready → devflow archive
+   │              → closed without merge → phase=deliver (decide: keep/discard/retry)
+   │
+   ├─ mode=merge → phase=archive_ready → devflow archive
+   │
+   ├─ mode=keep  → phase=deliver (搁置,可恢复)
+   │
+   └─ mode=discard → phase=archived (但 archive 类型是 discard)
+```
+
+---
+
+## 常见误用
+
+- **每次都 pr**,明明是个人项目 → 白绕一圈 → 合理用 merge
+- **每次都 merge**,团队项目没人 review → 合规风险,团队信任崩塌 → 必须走 pr
+- **keep 忘了还在 keep**:1 个月后看到 `devflow status` 里有 5 个 keep 的 change → orchestrator 应定期提醒
+- **discard 时 --purge 丢了有价值的 design 思考**:默认不 purge,除非真的没价值

package/skills/deliver/references/notify.md

@@ -0,0 +1,359 @@
+# deliver / notify
+
+SMTP / IM 通知模板、抄送策略、订阅机制。
+
+---
+
+## 通知的目的
+
+**让相关方知道"事情发生了"**,不能期望他们自动发现。
+
+典型场景:
+
+- PR 提出 → 通知 reviewer(code owners / 上游 PM / QA)
+- PR merge → 通知 QA 进入集成测试
+- PR discard → 通知 PM / stakeholder(需求状态变化)
+- hotfix merge → 通知 ops / on-call
+
+---
+
+## 配置 notify provider
+
+### SMTP(邮件)
+
+```jsonc
+{
+  "notify": {
+    "smtp": {
+      "driver": "notify-smtp",
+      "config": {
+        "host": "smtp.exmail.qq.com",
+        "port": 465,
+        "secure": true,
+        "auth": {
+          "user": "noreply@example.com",
+          "pass": "<from-vault-or-env>"
+        },
+        "from": "\"DevFlow Bot\" <noreply@example.com>"
+      }
+    }
+  }
+}
+```
+
+- 密码/凭据用 env var(`$SMTP_PASS`)或 secret manager,**不硬编码**
+- `devflow doctor --scope cred` 会扫这个 config 有无明文敏感字段
+
+### IM(飞书 / 钉钉 / 企微)
+
+driver 自己实现,config 里给 webhook URL。
+
+```jsonc
+{
+  "notify": {
+    "im": {
+      "driver": "notify-lark",
+      "config": {
+        "webhook": "$LARK_WEBHOOK",
+        "atMobiles": ["13800138000"]
+      }
+    }
+  }
+}
+```
+
+---
+
+## 触发方式
+
+### deliver 时
+
+```bash
+devflow deliver --mode=pr --notify
+# 默认使用 notify provider 中配置的 config.defaults.to / config.defaults.cc
+# 邮件正文来自 reports/submit.md；含变更概要、库表变更、测试重点、自测汇总
+# 默认只附一份汇总测试报告 reports/test-report.md
+# 输出 accepted by SMTP server 只代表 SMTP 接受；localhost/sendmail/postfix 只算本机入队
+```
+
+```bash
+devflow deliver --mode=pr --notify --to=team-a@example.com,team-b@example.com --cc=lead@example.com
+# 显式指定
+```
+
+```bash
+devflow deliver --mode=pr --notify --attach-docs --attach-reports
+# 只有确实需要原始 requirement/design/plan 或各类原始测试报告时才加
+```
+
+```bash
+devflow deliver --mode=pr --notify=test-report
+# 极简模式(L0)专用：发测试结果邮件（内含 test-report.md#unit + code-review 摘要）
+# state.mode=micro 时，deliver 自动追加此 flag
+```
+
+### hook(自动)
+
+配 `hooks.on_deliver`:
+
+```jsonc
+{
+  "hooks": {
+    "on_deliver": [
+      { "mode": "pr", "notify": "smtp", "to": ["team@example.com"] },
+      { "mode": "merge", "notify": "im", "when": "level=L3" },
+      { "mode": "pr", "notify": "test-report", "when": "level=L0", "to": ["team@example.com"] }
+    ]
+  }
+}
+```
+
+deliver 完成后自动触发对应 notify。
+
+---
+
+## 邮件模板
+
+### PR created
+
+```text
+Subject: [DevFlow] [coupon-batch-grant] 批量发放优惠券 API - PR #123 待审查
+
+Hi <reviewer>,
+
+PR 刚提交,辛苦帮忙 review。
+
+标题: [coupon-batch-grant] 批量发放优惠券 API
+级别: L2
+PR 链接: https://gitlab.example.com/group/repo/-/merge_requests/123
+
+变更概要:
+  新增批量发放 API,单批 ≤ 10000 条,支持 CSV 上传。
+
+范围:
+  - F-01 批量发放 API
+  - F-02 批量发放查询 API
+  - F-03 后台 UI 接入
+
+自测结果: 243/243 单测通过,self-test 12/12 AC 满足,P99 180ms (NFR 200ms)
+
+特别想听 feedback:
+  - 事务边界设计(见 ADR-003)
+  - batchId 使用 ULID 而非 UUID
+
+非常感谢!
+<author>
+
+---
+This email is automatically generated by DevFlow Kit.
+```
+
+### PR merged
+
+```text
+Subject: [DevFlow] [coupon-batch-grant] 已合并 → 请 QA 跟进集成
+
+Hi QA/on-call,
+
+[coupon-batch-grant] 已 merge 到 main(commit abc1234),准备进入集成测试 / rollout。
+
+Rollout 计划: design.md#rollout (feature flag 5% → 50% → 100%)
+回滚方案: design.md#rollback
+
+PR 链接: ...
+测试报告: verify.md
+
+请跟进。
+---
+Auto-generated
+```
+
+### 极简模式(L0)：测试结果报告
+
+`--notify=test-report` 触发，邮件正文从 `reports/submit.md` 汇总信息提取；其中 `库表变更` 会从 `design.md` 的 DDL / 数据层章节和根目录 `ddl.sql` 提取，列出新建表、新增字段、修改字段、删除字段。默认只附 `reports/test-report.md`。正文不要放本地 markdown 链接，也不要把 unit / integration / e2e / joint / remote / smoke / self-test 拆成多附件；测试同学需要技术方案和任务拆解时显式加 `--attach-design-plan` 只附 `design.md` / `plan.md`；需要全部原始材料时才显式加 `--attach-docs`、`--attach-reports` 或 `--attach=<path>`。
+
+```text
+Subject: [DevFlow][L0] [fix-null-pointer] 测试报告 — 单测全通过 ✅
+
+Hi Team,
+
+极简模式 change [fix-null-pointer] 已完成，测试结果如下。
+
+── 测试摘要 ──
+单测：243 通过 / 0 失败 / 0 跳过
+远程 API：4 通过 / 0 失败
+联调测试：2 通过 / 0 失败
+覆盖率：(如覆盖率工具可用：82%)
+Code Review：通过（1 轮，0 个 MUST 问题，2 个 SHOULD 已说明）
+
+── 改动说明 ──
+fix-null-pointer：修复 OrderService.findById 在 orderId 为 null 时抛 NPE 的问题。
+文件：src/service/OrderService.java（+3 -1 行）
+
+── PR/MR ──
+https://gitlab.example.com/group/repo/-/merge_requests/456
+
+如有疑问请查看 PR 或联系作者。
+---
+This email is automatically generated by DevFlow Kit (L0 micro mode).
+```
+
+> **发送时机**：`devflow deliver --notify=test-report` 在 deliver 完成后、但在 archive 之前（L0 无 archive）触发。
+> **收件人来源**：同标准策略（`--to` > `config.delivery.notify.defaultTo` > CODEOWNERS）。
+> **无 provider 时**：打 WARNING，不阻塞 deliver 主流程。
+
+---
+
+### PR discarded
+
+```text
+Subject: [DevFlow] [coupon-batch-grant] 已取消
+
+Hi <stakeholder>,
+
+change [coupon-batch-grant] 已 discard。
+
+原因: 需求已被 PM 取消(邮件 ABC123),优先级调整到 Q3。
+
+相关资产归档至: devflow/archive/discarded/coupon-batch-grant-20260424/
+
+如需重启,请新开 slug(不要复用旧目录,因为 spec 基线可能已漂移)。
+---
+Auto-generated
+```
+
+---
+
+## IM 模板(简短)
+
+飞书 / 钉钉消息一般短、图文。模板:
+
+```text
+🔔 [DevFlow] coupon-batch-grant - PR 待审查
+
+@reviewer_a @reviewer_b 辛苦 review
+
+📝 批量发放优惠券 API (L2)
+🔗 https://gitlab.example.com/.../merge_requests/123
+✅ 自测 12/12 pass | P99 180ms
+📊 单测 243/243 | 覆盖 86%
+
+focus 点: 事务拆三段的设计(ADR-003)
+```
+
+Markdown 支持的 IM(飞书富文本 / 钉钉 markdown):
+
+```markdown
+**[coupon-batch-grant] 批量发放优惠券 - PR #123**
+
+- 级别: L2
+- 自测: ✅ 12/12 AC
+- P99: 180ms (NFR 200ms)
+- [PR 链接](...)
+
+请 @reviewer_a @reviewer_b 审查。
+```
+
+---
+
+## 抄送 / 收件人策略
+
+### 收件人来源优先级
+
+1. `--to=<emails>`(命令行显式)
+2. `--notify-to=<emails>`(命令行显式)
+3. `notify.smtp` provider 的 `config.defaults.to`
+4. `notify.smtp` provider 的历史兼容字段 `config.defaultTo`
+
+抄送同理：`--cc` / `--notify-cc` 优先，未传时读取 `config.defaults.cc` / `config.defaultCc`。
+
+`devflow provider setup` 配置 `notify.smtp` 时会询问 `defaults.to` 和 `defaults.cc`，多个邮箱用逗号分隔。发送前必须展示 To / Cc 预览并让用户确认。
+
+### 抄送策略
+
+| 场景 | to | cc |
+| --- | --- | --- |
+| PR 待审查 | reviewer | code owner + PM |
+| PR merged | QA + on-call | 全团队 mailing list |
+| PR discard | stakeholder | 团队 lead |
+| hotfix merge | ops + on-call + 团队 lead | 管理层(若 P0) |
+
+### 订阅机制
+
+团队成员可以个性化订阅:
+
+```jsonc
+{
+  "notify": {
+    "subscriptions": {
+      "@alice": {
+        "events": ["pr-created", "pr-merged"],
+        "slugs": ["coupon-*", "order-*"],
+        "channel": "smtp"
+      },
+      "@bob": {
+        "events": ["pr-discard"],
+        "slugs": ["*"],
+        "channel": "im"
+      }
+    }
+  }
+}
+```
+
+`devflow deliver --notify` 会 merge 手动 to + 订阅匹配结果。
+
+---
+
+## 防骚扰
+
+- **单 change 去重**:同一 slug 同一事件(如 pr-created)在 24h 内只发一次,重复 deliver(比如 keep 后重新开)不重发
+- **静音时段**:非工作时间只发 P0 / hotfix,普通 change 次日早发
+- **订阅太宽的警告**:`devflow doctor` 会提示"有用户订阅了 100% 的 event,可能造成骚扰"
+- **一键退订**:邮件 footer 加退订链接(或指引到 `devflow notify unsubscribe <event>`)
+
+---
+
+## 敏感信息保护
+
+notify 内容会被外发,必须过滤:
+
+1. 不含 token / secret
+2. 不含 PII(用户手机 / 邮箱等不露全;露一部分替代)
+3. 不含内部 URL(除非收件人是团队内部)
+
+`devflow deliver --notify` 发送前扫描内容,命中敏感模式:
+
+- **token 模式**:拒绝发送
+- **URL 模式**:如果内含 `.internal` / `.local` 域名,确认收件人 domain 匹配
+- **PII 模式**:警告(可继续)
+
+---
+
+## 错误处理
+
+notify 发送失败:
+
+- 不阻塞 deliver 主流程(PR 已经提了)
+- state.delivery.notify 记 `status: failed`,`error: ...`
+- 可 `devflow deliver --notify --retry` 重发
+- 超过 3 次失败,`devflow doctor` 报 concern,可能是 provider 配置 / 凭据问题
+
+---
+
+## 不要用 notify 做的事
+
+- **当 chat**:notify 是单向广播,不要指望回复(reply 到 noreply@ 会 bounce)
+- **当进度条**:每 5 分钟发一次"还在 build 中" → 退订高发
+- **当 code review**:review 是 PR 里的 thread,不是邮件来回
+- **发 PR diff 全文**:IM 容量有限,邮件也不友好;用 PR 链接
+
+---
+
+## 本地测试
+
+```bash
+devflow provider test notify.smtp --to=me@example.com --subject="test" --body="test body"
+```
+
+发一封测试邮件,验证 SMTP 配置对。IM 同理。