贡献规范落地：CONTRIBUTING.md + Docs Gate 门禁 + PR 模板（工程文档不入仓这条目前无机械约束） #137

问题

《GitHub 过程管理规范》里「工程文档不入仓」这一条，目前没有任何机械约束，而且已经在真实发生：

• PR docs: remove migrated module split doc #128 于 2026-08-06 02:35 合并，删掉 docs/module-split.md，说明「内容已迁到 Issue」——做的是对的事。
• PR feat: integrate verified Windup source snapshot #126（源码快照整合，271 文件）把 docs/module-split.md 又改了回来，并新增 docs/module-split-plan.md、docs/sse-generation-flow.md、docs/superpowers/plans/2026-08-05-*.md（2 份）、docs/superpowers/specs/2026-08-05-*.md（2 份）、根目录 api-reference.md。

这不是谁不小心。 改动一大，md 就藏在两百多个文件里，评审时没人会专门去看。规范只写在群消息和营规范原文里，新加入的人和各种 AI agent 都读不到——规范没有落点，就只能靠记性。

提议

三个文件，都在 .github/ 与仓库元文件范围内，不含任何设计或架构内容：

外加一个新 label user-doc，作为门禁的豁免开关。

为什么规范放 CONTRIBUTING.md 而不是 Issue

「工程文档不入仓」针对的是会分叉的设计描述：文档 commit 进仓后代码继续演进而 md 不动，半年后没人知道哪份算数。贡献规范正好相反——它必须和 CI 配置、目录结构一起演进才有意义。改了 naming.yml 的正则却没同步规范，这个不一致应该在同一个 PR 的 diff 里被看见；放进 Issue 反而制造分叉。

另外它面向的是仓库使用者，CONTRIBUTING.md 是 GitHub 原生识别的文件（开 Issue / PR 时会自动提示），这是它的标准位置。

门禁的设计原则：宁可漏拦，不可误拦

误伤别人正常工作的门禁会被直接关掉，所以它只管两个最明确的位置：

• 拦：docs/** 下的新增与修改、仓库根目录的新增 md
• 不拦：删除（把文档搬走正是我们想要的）、子目录里的 README / MODULES.md、允许清单里的路径、打了 user-doc 的 PR

子目录 md 故意不拦，因为团队实际约定是「未对齐点显式落 README / MODULES.md，不留聊天记录」。这条和「工程文档不入仓」确有张力，CONTRIBUTING.md 2.1 里把当前口径写成了「记录结论可以入仓，记录论证过程进 Issue」——这个口径是提议的，不是既有规范里的，请评审时确认或修正。

拿全部 15 个 open PR 实测过

不是纸上推演，是把每个 open PR 的真实文件清单喂给门禁逻辑跑了一遍：

#74 / #72 那类假警报值得单说：它们「新增」frontend-architecture-v3.md，但那文件 main 上早就有——是分支落后导致 merge-base 把老文件算成新增，rebase 后自动消失。门禁的报错信息里已经写明这一点并给出 rebase 命令，让假警报变成「你该 rebase 了」的有用信号。

建议的推进方式

1. 先不要设成 required check。 跑两周看误伤率再谈。现在设 required，feat(quick-start): add workflow-backed creation flow #74 / feat(workflow-run): add frontend execution foundation #72 那种陈旧 base 的 PR 会直接被卡死。
2. user-doc label 已建好（区别于 Issue 上的 Documented 状态标签——一个是 PR 门禁开关，一个是 Issue 生命周期，语义不同不要互相代用）。
3. 存量问题不在本次处理：根目录 frontend-architecture-v3.md 属同类，处理它要单独开 PR。feat(generation): align validated SSE adapter with backend tasks #110 / feat(media): add validated upload adapter #111 的 _PR说明.md 也请各自作者自行决定。

验收

• 门禁对本 PR 自身放行（CONTRIBUTING.md 与 .github/** 在允许清单内）
• 构造一个含 docs/design.md 的 PR 会被拦下，打上 user-doc 后放行
• 新开 PR 时自动带出模板