feat(gate): 新增 E_WAIT_LANGUAGE——交接件正文禁「让前端等我们」的措辞
changelog-filename-gate / validate (push) Failing after 2s

2026-09-21 wx 第二次点名:「不要在changelog里写让前端等待部署 这不是你第一回犯错了
工作流是你部署完测试环境推送changelog」。

§2.1 的 backend_status 门禁挡得住预告式推送,挡不住这一类:20_7443 的 frontmatter
已经是 deployed、CI 全绿,但正文 status_note 结尾写着「该缺陷已在修……修好后另发
交接件」。mmg 因此一直没动工,隔天才来问「这个是有啥问题吗 还是没做到呢」——门禁
只看 frontmatter,看不见自由文本里的这句话,所以「deployed + 校验绿」并不代表这份
交接件可执行。消费方也没有能力消解这种不确定性:他查不了我们的部署状态、看不到
dev-v3、不知道「另发」是哪天,读到「等」就只能等,而且是静默地等。

- scripts/validate-changelog-frontmatter.mjs:新增 validateNoWaitLanguage,对所有
  v2 文档逐行扫描(与 change_type 无关,前端条目同样适用)。三类措辞:部署状态对冲、
  未来交付承诺、直接叫停对接;「等待」做共现判定而非裸词匹配,避免把「前端需轮询
  等待支付回调」这类业务语义一起拦掉。前向引用(「以后续订正为准」「见后续订正」)
  一并封住——它和「修好后另发」是同一件事换个说法,实测被绕过一次。
- tests:4 个用例,含 1 个阴性对照(灰度开关状态、已知缺口工单号、业务流程里的等待
  必须放行),防止作者为了过门禁把该写的契约边界一起删掉。
- BACKEND_CHANGELOG_DELIVERY_GUIDE.md §2.1:写明规则、背景与那条分界线——这条影响
  他「怎么写代码」,还是只影响他「什么时候开始写」?后者一律删。

阳性对照:对已推送的 HEAD 版 20_7443 跑新规则,命中 2 处(第 308、451 行「修好后另发」),
即它能抓住真实发生过的那次。既有 changelog-path-aliases 测试对 11_7510 的 2 条
E_ALIAS_STATE 红是本次改动之前就存在的,与本提交无关,pre-push 钩子也不跑该用例。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
这个提交包含在:
API Changelog Bot
2026-09-21 15:27:37 +08:00
共同撰写人 Claude Opus 5
父节点 b4fbfe6f20
当前提交 047a4be4fd
共修改 3 个文件,包含 117 行新增和 0 行删除
+6
查看文件
@@ -64,6 +64,12 @@ verified_at: ""
- 接口类条目(新增接口/修改接口/删除接口):推送前必须走完「PR 合并 → 部署测试服 → 测试服真实 API 验证」,frontmatter 必须 `backend_status: "deployed"`,并在正文「验证证据」章节贴实测结果。
- `backend_status` 为 `merged` / `pending` / `implemented` 等未部署状态的条目**禁止 push**(校验规则 E_BACKEND_PENDING 会拦)。「先给前端契约、部署随后」的预告式推送一律禁止——前端拿到 changelog 会立刻联调,接口不在等于空耗与误判。
- 🔴 **正文里不得出现任何「让前端等我们」的措辞**(2026-09-21 wx 第二次点名,校验规则 `E_WAIT_LANGUAGE` 会拦):`等部署` / `待部署` / `未部署` / `稍后另发` / `修好后另发` / `另发交接件` / `暂不可用` / `暂缓对接` / `该缺陷已在修` / `自行确认部署`,以及「等待」与「部署/后端/我们/上线/修复/另发/发版/滚动」同行共现。
- **为什么 §2.1 的 `backend_status` 门禁不够**:它是 frontmatter 字段,而这类句子活在自由文本里,门禁一个字也看不见——`deployed` + 校验器全绿**不等于**这份交接件可执行。2026-09-20 的 `20_7443` 就是这样:frontmatter 已 `deployed`、CI 绿,正文 `status_note` 结尾一句「该缺陷已在修……修好后另发交接件」,mmg 因此一直没动工,直到 09-21 才来问「这个是有啥问题吗 还是没做到呢」。
- **为什么不能交给前端自己判断**:消费方查不了我们的部署状态、看不到 `dev-v3`、不知道「另发」是哪天。我方如实写下的「未核」,到他那里只剩一个可选动作——等,而且是静默地等:文件推了、门禁绿了、日报也记了,唯一的异常信号是有人在安静空转,比压根没发更难发现(没发至少还会有人来催)。**对 wx 该说「没核」,对下游只能说「能接」,或者干脆先别发。**
- **正文只允许两类内容**:①已经就绪的契约;②前端调用时会撞上的限定(灰度开关状态、前置字段要求、会抛的错误码、已知缺口的工单号)。分界线是问一句:**这条影响他「怎么写代码」,还是只影响他「什么时候开始写」?**后者一律删掉。
- **某部分确实还没就绪时**:要么整份不发,要么把没就绪的那块**整段删掉**,只交他现在就能接的部分;绝不写成「稍后另发」。
- ⚠️ 本规则只拦我方在制品,**不拦契约边界**——「生产环境灰度开关尚未开启(属独立运维动作)」「TRANSFER-only 订单在 9 个下游消费方无产出,已记 #8056」这类必须照写,否则就撞上「交接件要把自己的覆盖范围写在脸上」那条相反的要求;`E_WAIT_LANGUAGE` 配了阴性对照用例保证不误拦这类句子。
- 纯前端条目(前端缺陷/前端优化/前端修复):`backend_status: "not_required"`,change_type 用对应前端类型;`frontend_status: "not_required"` 时不得残留 frontend_owner / frontend_ref / target_release / verified_at。
- 背景:2026-08-06~08-07 三条未部署即推送的条目(#5599/#5567/#5633)导致前端在测试环境验不到字段(2026-08-10 投诉属实);当时仓库 CI 因校验规则假阳性长期常红被忽略,规则已于 2026-08-10 修正(前端条目类型合法化、`{orderId}` 路径参数不再误判为占位符),此后 **CI 红 = 真违规,必须当场修复回填**。