@chenguangyao/devflow-kit 0.1.43

package/skills/complexity-grading/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: devflow-complexity-grading
+description: |
+  devflow-kit 复杂度分级器。在任何需求（URL / JIRA / idea / incident）进入开发流程后、
+  requirement-analysis 开始前，**自动触发**一次分级评估，输出 L0/L1/L2/L3
+  并等用户确认，然后写入 state.json.level。后续所有 phase 的尺度都基于此。
+when_to_use: |
+  - 用户粘贴 URL / JIRA ID / 描述 idea 后，在 requirement-analysis 前自动插入
+  - devflow ingest 完成后自动调用（state.currentPhase = intake 时）
+  - brainstorm 产出 proposal.md 后自动调用（state.currentPhase = brainstorm 时）
+  - 用户说"帮我重新评级"/ "level 对不对"/ "升级到 L3"时，手动触发
+  - 不要等用户主动问；也不要在 apply/review/verify 阶段反复触发
+---
+
+# complexity-grading
+
+**自动分级器**，不做实质工作。读现有材料 → 按维度打分 → 给用户看判定卡 → 等确认 → 写 state。
+
+---
+
+## 触发时机（自动）
+
+| 前驱 phase | 触发条件 | 动作 |
+| --- | --- | --- |
+| `intake` | `devflow ingest` 成功，`refs/source.md` 落盘 | **立即**读 `source.md` 做初判 |
+| `brainstorm` | `proposal.md` Done Criteria 满足 | **立即**读 `proposal.md` 做初判 |
+| 用户主动说明改动 | 用户在对话中给出"改 X 文件"/"新增 Y 接口"等信号 | 边听边更新初判，第一次稳定后输出判定卡 |
+
+触发后进入本 skill，**不等用户发第二条消息**，直接输出判定卡（见下文格式）。
+
+---
+
+## 执行步骤
+
+### Step 1：收集信号
+
+读以下任意已有材料（有什么读什么，不强制所有都存在）：
+
+| 材料 | 读取内容 |
+| --- | --- |
+| `refs/source.md` | 需求描述、功能列表、改动范围提示 |
+| `proposal.md` | 用户描述的想法、范围 |
+| `refs/incident.md` | 事故描述、影响面、修复方向 |
+| `refs/kb-context.md` | **KB 预检索结果**（ingest 阶段已写入，有则读，无则跳过） |
+| `state.json#projects` / `state.json#projectRouting` | ingest / new 阶段识别到的 primary / dependency 项目推荐 |
+| 用户对话上下文 | 口头说的文件名、接口、数量 |
+| `devflow/specs/` | 已有的 spec 文件（判断本次是否影响已有契约） |
+
+**不要**在此阶段读代码文件或做 grep 搜索（那是 requirement-analysis Round 2 的事）。
+
+同时提炼一张**问题卡**，用于让用户确认"我们到底在处理哪个问题"：
+- 标题：优先取 `proposal.md` 标题，其次取 refs 首个标题。
+- 来源：Wiki / JIRA / incident / manual 及原始 ref。
+- 现象/目标：用 1-3 条短句概括，不展开需求分析。
+- 已导入材料：change slug、refs 文件、图片/附件数量、KB 命中摘要（如有）。
+- 明显不确定项：只列会影响定级或项目范围的 1-3 个点。
+
+若 `state.json#projects` 存在，必须把它作为**涉及项目确认**展示；若不存在但 `projectRouting.candidates` 存在，展示候选并要求用户选择 primary / dependency。此确认和复杂度确认是同一个闸门，不能分散到 requirement 阶段才第一次让用户看到。
+
+**KB 命中参考规则**（读 `refs/kb-context.md` 后应用）：
+
+| KB 命中情况 | 对分级的影响 |
+| --- | --- |
+| 命中同类功能，历史 level=L3 | 本次**起评 L2**，不得低于 L2（除非用户明确说明范围更小） |
+| 命中同类功能，历史 level=L2 | 在判定卡中标注"历史同类为 L2"，供用户参考 |
+| 命中"曾踩坑 / 曾升级" | 在判定卡"⚠ 风险提示"中引用原文 |
+| 无命中 | 忽略，按常规维度打分 |
+
+---
+
+### Step 2：逐维度打分
+
+对下表 **10 个维度**逐一判级，无信号时默认 L1（保守估计）：
+
+| 维度 | L0 信号 | L1 信号 | L2 信号 | L3 信号 |
+| --- | --- | --- | --- | --- |
+| **代码规模** | 单处改动、已明确 | 单文件、diff < 100 行 | 2-8 文件、diff < 500 行 | > 8 文件 / 跨多模块 |
+| **数据层** | 无 | 无 DDL | 有 DDL（幂等可回滚） | 跨表 / 大表改列 / 数据迁移 |
+| **对外契约** | 无 | 无接口变更 | 新接口 / 改字段（兼容） | 删字段 / 改语义 / 跨服务契约 |
+| **并发 / 一致性** | 无 | 单路径 | 单表事务 | 分布式锁 / Saga / 最终一致 |
+| **性能要求** | 无 | 用户无感知 | 不退化即可 | 明确 SLO / 压测 / 容量 |
+| **安全 / 合规** | 无 | 无敏感数据 | 权限校验 / 脱敏 | 合规审计 / 隐私变更 |
+| **团队 / 依赖** | 一人 | 一人 | 本团队 2-3 人 | 跨团队 / 跨部门 |
+| **灰度 / 回滚** | 无 | 不需要 | 简单 feature flag | 分批灰度 + 白名单 + 演练 |
+| **监控 / 告警** | 无 | 不需要 | 加指标 | 加指标 + 告警 + runbook |
+| **测试类型** | 单测（≤ 1 个） | 单元 + 冒烟 | + 集成 | + e2e / 性能 / 回归 |
+
+**综合判定规则（就高不就低）：**
+1. 任一维度命中 L3 → 整体 L3
+2. 任一维度命中 L2 → 整体 ≥ L2
+3. 所有维度 ≤ L1，且用户已明确改法 → L0 候选（需用户确认）
+4. 无法判断某维度 → 默认 L1（不降低保守估计）
+5. 拿不准整体 → 默认 L2
+
+---
+
+### Step 3：输出判定卡（必须用此格式）
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  问题卡：早筛幽门结果导入功能                            │
+├─────────────────────────────────────────────────────────┤
+│  来源：Wiki #142565872                                  │
+│  change：feature-hp-import                              │
+│  材料：refs/intake-wiki.md；图片 6 张；KB 命中 2 条       │
+│  目标：导入早筛幽门结果，生成成功/失败明细               │
+│  不确定项：失败明细字段、重复导入策略                    │
+├─────────────────────────────────────────────────────────┤
+│  涉及项目确认：                                          │
+│    primary    → health-mall                              │
+│    dependency → health-marketing, health-portal           │
+│    候选       → health-mall-local, health-user            │
+│                                                         │
+│  如需修改：回复 项目=health-mall,health-user             │
+│  如不关联代码项目：回复 项目=none                        │
+├─────────────────────────────────────────────────────────┤
+│  复杂度初判：L2                                          │
+├─────────────────────────────────────────────────────────┤
+│  维度打分：                                              │
+│    ✓ 代码规模   → L2（预计改 4-6 个文件）               │
+│    ✓ 数据层     → L2（新增 1 张表，DDL 可重入）         │
+│    ✓ 对外契约   → L2（新增 1 个接口，字段兼容）         │
+│    · 并发一致性 → L1（单表事务）                        │
+│    · 安全合规   → L1（无敏感数据）                      │
+│    · 团队依赖   → L1（一人完成）                        │
+│    · 其余维度   → L1                                    │
+│                                                         │
+│  综合：取最高维度 → L2                                  │
+├─────────────────────────────────────────────────────────┤
+│  L2 流程包含：                                          │
+│    requirement（双轮） → design → test-spec → plan      │
+│    → apply → code-review → verify（unit+集成） → deliver│
+│    → archive                                            │
+│                                                         │
+│  ⚠ 若后续发现 DDL 有跨服务一致性 → 升 L3               │
+│  📚 KB 历史参考：上次"会员权益升级"定为 L2（见 kb-context）│
+├─────────────────────────────────────────────────────────┤
+│  请确认：                                               │
+│    回车 = 确认问题卡 + 项目 + L2，继续 requirement-analysis │
+│    L0 / L1 / L3 = 调整级别（请说明原因）               │
+│    项目=<primary>[,<dependency>] = 修改涉及项目          │
+│    ? = 我来解释每个维度的判断依据                       │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+### Step 4：等待用户确认
+
+**确认字段防伪规则（硬约束）**：
+
+- `problemCardConfirmedAt` 和 `projectConfirmationAt` 只能在本 skill 写入；其他 skill 不能代写。
+- 写入前，当前回复正文必须已经完整展示"问题卡 + 涉及项目确认 + 复杂度初判"。
+- 只有用户明确确认上一条回复里的判定卡后，才能写 `state.json`。仅有"继续"、"下一步"、"没有问题"但上一条回复没有展示判定卡时，不算确认。
+- 如果发现旧状态已有 `state.level` 但缺少确认字段，必须重新展示简版问题卡并等待用户明确确认，不得直接补写字段。
+- 如果用户修改项目或级别，先重出判定卡摘要，再等下一次确认。
+
+| 用户响应 | 处理 |
+| --- | --- |
+| 回车 / "确认" / "OK" | 写 `state.level = <判定级>`，保留当前 `state.projects` → 进入下一 phase |
+| `L0` / `L1` / `L2` / `L3` | 询问"调整原因？"→ 记 audit → 写新 level → 进入下一 phase |
+| `项目=<primary>[,<dependency>]` | 更新 `state.projects` 与 `state.projectRouting.recommended`，重新展示判定卡摘要，等待确认 |
+| `项目=none` | 清空本次 `state.projects`，记录"暂不关联代码项目"，重新展示判定卡摘要，等待确认 |
+| "项目不对" / "换项目" | 展示候选项目和命令格式，不写 level，等待用户给出 `项目=...` |
+| `?` 或 "为什么" | 逐维度解释判断依据，不重新判级，再次等确认 |
+| "改动比我说的大" | 重新收集信号，更新打分，再次输出判定卡 |
+
+---
+
+### Step 5：写 state.json
+
+```json
+{
+  "level": "L2",
+  "levelSetAt": "<ISO timestamp>",
+  "levelSource": "complexity-grading",
+  "problemCardConfirmedAt": "<ISO timestamp>",
+  "projectConfirmationAt": "<ISO timestamp>",
+  "projects": [
+    {
+      "name": "health-mall",
+      "root": "/path/to/health-mall",
+      "role": "primary"
+    }
+  ],
+  "levelAudit": [
+    {
+      "type": "initial_grading",
+      "level": "L2",
+      "scores": {
+        "代码规模": "L2",
+        "数据层": "L2",
+        "对外契约": "L2",
+        "并发一致性": "L1"
+      },
+      "confirmedBy": "user",
+      "confirmedProjects": ["health-mall"],
+      "at": "<ISO timestamp>"
+    }
+  ]
+}
+```
+
+写完后输出：
+```
+✔ level=L2 和涉及项目已写入 state.json，进入 requirement-analysis。
+```
+
+---
+
+## 特殊场景
+
+### 极简模式（L0）的识别与确认
+
+L0 是最严格的级别（paradox：最轻的流程但最严的前置条件）：
+
+**自动识别信号**（需全部满足）：
+- 用户明确说"极简"/"不要文档"/"直接改"
+- 改动描述具体到文件名 + 行号 / 函数名
+- 无 DDL / 无接口变更 / 预计 ≤ 1 个文件
+
+输出判定卡时，额外显示：
+
+```
+⚠ L0 极简模式：跳过所有文档 phase，直接 apply → code-review → verify → deliver（含测试邮件）
+⚠ 如果 apply 过程中发现改动超出 1 个文件，必须升级到 L1。确认继续？
+```
+
+### 升级触发（中途发现）
+
+非本 skill 阶段（如 apply 时发现 DDL），其他 skill 可调用：
+
+```
+devflow status set-level L3 --reason="发现跨服务数据一致性问题"
+```
+
+本 skill 不处理中途升级，仅负责初始定级。
+
+---
+
+## 不做的事
+
+- **不做 requirement-analysis**：读需求 + 判级，不问"边界条件是什么"
+- **不做 brainstorm**：不扩展用户的想法，只从现有材料提取信号
+- **不替用户拍板**：判级卡必须等用户确认后才写 state，不能默默写
+- **不反复触发**：一个 change 只在 intake/brainstorm 完成时触发一次初判；后续 phase 不重复触发，除非用户主动要求重新评级
+
+---
+
+## 完成状态协议
+
+```
+---STATUS---
+result: DONE | NEEDS_INPUT
+level: L0 | L1 | L2 | L3
+confirmedBy: user | auto (auto 仅在 --ci 模式且 level 无争议时)
+nextPhase: requirement | plan (L0 直接 plan)
+---END_STATUS---
+```

package/skills/deliver/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: devflow-deliver
+description: |
+  devflow-kit deliver 阶段交付 change。4 种模式 —— `pr`(默认,提 PR/MR)、`merge`(本地合并)、`keep`(搁置)、
+  `discard`(丢弃,危险)。自动构建 PR/MR 描述(标题、提测自测、关联文档、回滚方案),
+  可选 notify(SMTP / IM)。硬闸:verify.status=completed、review.status=completed、
+  `devflow doctor` 无 error。触发:`devflow deliver [--mode=<m>]` 或 `/df:deliver`。
+when_to_use: |
+  `devflow verify finalize` 通过后。根据项目流程选 mode。 pr / merge 后提醒用户等 MR 合并 / 上线后接
+  `devflow archive`，archive 会合并 specs 并执行 knowledge deposit / sync / MR;keep 搁置等复工;
+  discard 需确认后彻底清理。
+---
+
+# deliver
+
+**交付专家**,不是实现者。代码和文档已齐,verify 通过;deliver 把它"安全、可追溯、可回滚"地送到集成轨道。
+
+## 前置硬闸
+
+| 条件 | 必需 | 失败处理 |
+| --- | --- | --- |
+| `state.verify.status === "completed"` | 是 | 退回 verify,除非 `--skip-verify`(审计) |
+| `state.review.status === "completed"` | 是 | 退回 review,除非 `--skip-review`(审计) |
+| `devflow doctor --scope cred` 无 error | 是 | 修完再来(credential 泄露 → 报告里不能含明文 token) |
+| 分支不是 `main/master/default` | 是 | 切到 feature 分支再发 |
+| git 工作区干净(无未提交) | 是 | 先 commit / stash |
+| 所有 task 都 commit 到当前分支 | 是 | 回退 apply 补 |
+
+每个硬闸的跳过都要走 `--skip-<gate> --reason="..."`,并记进 state.json 的审计日志。
+
+## 4 种 Mode 的决策
+
+```
+想让别人 review / CI 跑 → pr     (默认)
+个人项目 / 微不足道修复,直接合 → merge
+想搁置几天再回来 → keep
+完全放弃这个 change → discard
+```
+
+详细决策矩阵 + 组织规范建议:见 [`references/delivery-modes.md`](references/delivery-modes.md)。
+
+## Mode: `pr` (默认)
+
+### 构造 PR/MR 描述
+
+自动拼装:
+
+```markdown
+# [<slug>] <change.title>
+
+## 变更概要
+<requirement.md#背景 + change.summary>
+
+## 范围
+- F-01, F-02, ... (from requirement.md)
+
+## 提测自测
+<verbatim reports/test-report.md#self-test 的验收 / 自测区块>
+
+## 关联文档
+- [proposal](devflow/changes/<slug>/proposal.md)
+- [requirement](devflow/changes/<slug>/requirement.md)
+- [design](devflow/changes/<slug>/design.md)
+- [plan](devflow/changes/<slug>/plan.md)
+- [review](devflow/changes/<slug>/review.md)
+- [verify](devflow/changes/<slug>/verify.md)
+
+## 回滚方案
+<design.md#rollback>
+
+## reviewer 提示(手动追加)
+```
+
+构造规则、描述风格、提交给 reviewer 的视角转换:见 [`references/pr-description.md`](references/pr-description.md)。
+
+### 提交到哪
+
+- 若配了 `vcs.<provider>`(`vcs.gh`、`vcs.gitlab`、`vcs.bridge`) → 用 provider 调 API 提
+- 否则尝试 `gh` CLI(GitHub)
+- 否则 print 出 PR body,让用户手动粘贴
+
+### 常用 flags
+
+```
+--reviewers=@alice,@bob    指定 reviewer(视 provider 支持)
+--labels=bugfix,l2         加 label
+--target=develop           目标分支(默认由 devflow init 自动检测,master / main 均兼容)
+--draft                    Draft PR / Work-in-progress MR
+--notify                   用 notify provider 发通知(SMTP 邮件 / IM)
+```
+
+## Mode: `merge`
+
+本地直接合并到目标分支(默认用 `devflow init` 检测到的默认分支,`master` 或 `main`)。
+
+```bash
+devflow deliver --mode=merge                      # 默认分支(自动检测)
+devflow deliver --mode=merge --target=master      # 显式指定 master
+devflow deliver --mode=merge --target=main        # 显式指定 main
+```
+
+执行(假设默认分支为 master):
+
+1. `git checkout master`
+2. `git merge --no-ff <feature-branch>` (或 rebase,看项目配置)
+3. 不 push(用户自己决定)
+4. state.delivery.mode = "merge",记录 merge commit sha
+
+**典型场景**:
+
+- 个人 / 小团队项目,没 CI 门禁
+- hotfix 紧急修复(但要立刻跟 archive)
+- 文档 / 配置微改
+
+**不推荐场景**:
+
+- 正常 feature(应走 PR 让他人 review)
+- 团队项目(绕过 review 流程)
+- 需要 CI gating 的项目
+
+## Mode: `keep`
+
+不提、不合、不丢,就地搁置。
+
+```bash
+devflow deliver --mode=keep --reason="等上游依赖合完再走"
+```
+
+- state.delivery.mode = "keep"
+- state.phase 保持 deliver
+- `devflow status` 列为 "pending delivery",到时再 `devflow deliver --mode=pr` 继续
+
+**典型场景**:
+
+- 等上游 change 合并
+- 等用户 / PM 确认方案
+- 临时搁置(最多 1-2 周,否则考虑 discard)
+
+## Mode: `discard`
+
+彻底放弃 change,清理痕迹。
+
+```bash
+devflow deliver --mode=discard --reason="需求已取消"
+```
+
+执行**前必须二次确认**,交互式:
+
+```
+[CONFIRM] This will permanently delete devflow/changes/<slug>/. Type the slug to confirm:
+> <slug>
+```
+
+清理:
+
+- 移除 `devflow/changes/<slug>/`(可选 `--keep-archive` 归档到 `devflow/archive/discarded/<slug>/`)
+- 删本地分支 `devflow/<slug>/*`(可选 `--keep-branches`)
+- 清 worktree
+- state 整体删除
+
+**默认行为**:discarded change 归档到 `devflow/archive/discarded/<slug>/` + 留 `DISCARD.md`(reason + timestamp + who),**不是**物理删除。要彻底删用 `--purge`。
+
+**典型场景**:
+
+- 需求被取消(PM 撤方案)
+- 走不通的 spike(保留 knowledge 里即可,不走 deliver)
+- 方案错误,重做(重做应开新 slug,不改旧 slug)
+
+## Notify(可选)
+
+配了 `notify.smtp` / `notify.im` provider 后:
+
+```bash
+devflow deliver --mode=pr --notify
+```
+
+发邮件 / IM 通知,内容默认是:变更概要 + 库表变更 + 测试重点 + 自测汇总。库表变更从 `design.md` 的 DDL / 数据层章节和根目录 `ddl.sql` 提取，正文里要列出新建表、新增字段、修改字段、删除字段。SMTP 收件人优先使用 `--to/--cc`；未传时读取 `notify.smtp` provider 的 `config.defaults.to` / `config.defaults.cc`。这些默认收件人可在 `devflow provider setup` 里配置，发送前必须预览 To / Cc 并确认。
+
+邮件正文不要写本地 markdown 引用链接。`reports/submit.md` 作为正文和本地留档；默认只附一份汇总后的 `reports/test-report.md`，其中要合并 unit / integration / e2e / joint / remote / smoke / self-test / deploy 结果，并把联调测试按"环境信息、执行结果、用例执行详情、失败详情"整理出来。测试同学需要技术方案和任务拆解时，显式加 `--attach-design-plan` 只附 `design.md` / `plan.md`；确实需要全部原始材料时,才显式加 `--attach-docs` / `--attach-reports` / `--attach=<path>`。
+
+发送结果必须区分"外部 SMTP 接受"和"本机 MTA 入队"。本机 `sendmail` / `postfix` / `localhost:25` 接受消息时,只能说 queued by local SMTP/MTA,不能说真实送达；需要提示检查 mail queue / provider 日志。
+
+### 极简模式(L0)：测试邮件
+
+极简模式下 deliver 完成后 **必须** 发测试结果邮件（取代 PR review 通知，因为 L0 通常直接 merge）：
+
+```bash
+devflow deliver --mode=pr --notify=test-report
+# 或极简模式自动触发（state.mode=micro 时 deliver 默认追加 --notify=test-report）
+```
+
+邮件内容自动从 `reports/submit.md` 和 `reports/test-report.md` 提取：
+
+- 测试总数 / 通过数 / 失败数
+- 覆盖率（如有）
+- 失败用例明细（如有）
+- code-review 结论摘要（来自 `code-review-report.md`）
+
+> **必须配 notify provider 才能发**。若未配，deliver 仍正常完成，但会在输出中打 WARNING：
+> ```
+> ⚠ --notify=test-report: no notify provider configured. Skip sending.
+>    配置方法: 参考 ~/.devflow/providers.example.json 复制 notify.smtp 到
+>    ~/.devflow/providers.json，或执行 devflow provider setup → 选 notify.smtp
+> ```
+
+模板、抄送规则、订阅机制:见 [`references/notify.md`](references/notify.md)。
+
+## 回滚方案(必写)
+
+PR 描述里必须有 "回滚方案" 段,源自 design.md。如果 design.md 没有,deliver 会提示补写(回退 tech-spec),**不接受"一句话 rollback: git revert"**。
+
+rollback 必须含:
+
+- 触发条件(什么指标/现象触发回滚)
+- 步骤(分几步)
+- 影响(数据 / 下游 / 用户)
+- 验证(回滚后如何确认 OK)
+
+详见 [`../tech-spec/references/rollout-and-rollback.md`](../tech-spec/references/rollout-and-rollback.md)。
+
+## 凭据安全自动扫描
+
+`devflow deliver` 内部会:
+
+1. 扫 reports/ 下所有 md 是否含 token / secret 模式(AKIA*, ghp_*, JWT-like)
+2. 扫 PR body 是否含 token
+3. 扫 git diff 是否含 key 文件(`.pem`, `.key`, `.env`)
+
+任一命中 → 拒绝提交,提示修。审计绕过需 `--allow-secrets`(极不推荐)。
+
+## 完成状态协议
+
+```
+---STATUS---
+result: DONE | BLOCKED | NEEDS_INPUT
+deliveryMode: pr | merge | keep | discard
+prUrl: https://gitlab.example.com/group/repo/-/merge_requests/123
+mergeSha: abc1234 (merge mode)
+discardedTo: devflow/archive/discarded/<slug>/ (discard mode)
+notified:
+  - email: ["@team-a@example.com"]
+  - im: "#coupon-dev"
+testReportNotified: true | false | skipped  # 极简模式(L0)时额外字段
+nextAction: after MR merged / change live, run devflow archive
+knowledgeReminder: archive will merge specs and run knowledge deposit / sync / MR when configured
+---END_STATUS---
+```
+
+> **极简模式(L0)**：`nextAction` 为空（不进 archive）；`testReportNotified` 字段必须存在。
+> **非 L0 必须提醒知识沉淀**：deliver 完成时不能只说“交付完成”。必须明确告诉用户：合并或上线后运行 `devflow archive`，该步骤会把 delta 合并到 specs，并从 workspace/change 产物自动执行知识沉淀；如果配置了 `kb.git` / `kb.weknora`，还会继续走 KB MR、push 或 sync。
+
+## 反模式
+
+- **跳过 verify 硬闸**直接 deliver → 生产 bug 的温床
+- **PR body 拷 verify 表**:verify 是 dashboard,PR 要自测证据
+- **rollback 写一句"git revert"**:信息量零
+- **把 self-test 截屏一张图算完**:reviewer 不可能看清
+- **discard 直接 `rm -rf`**:必须走 --mode=discard,留 DISCARD.md
+- **merge mode 走正式 feature**:绕过 review,不符合流程
+- **keep 超 2 周不动**:要么 discard,要么继续,不能无限挂
+- **deliver 后立刻 archive**:必须等 merge / 上线后再 archive(否则 spec 与生产不一致)
+- **多 change 同时 merge/pr 没协调**:下游 conflict 风暴;orchestrator 应协调
+- **PR body 贴 token**:已有自动扫描,但别依赖它,主动检查
+- **notify 一次全公司 cc**:只发利益相关方
+
+## 参考
+
+- [`references/delivery-modes.md`](references/delivery-modes.md) — 4 种 mode 的详细决策树、组织规范建议、边界 case
+- [`references/pr-description.md`](references/pr-description.md) — PR/MR 描述构造规则、reviewer 视角、范例、反模式
+- [`references/notify.md`](references/notify.md) — SMTP / IM notify 模板、抄送策略、订阅机制
+- [`../tech-spec/references/rollout-and-rollback.md`](../tech-spec/references/rollout-and-rollback.md) — 回滚方案模板(与 tech-spec 共享)