Quality gates

Quality gates 表示仓库把“什么叫可以合并、什么叫可以发布”写成了显式、可审计的契约，并通过本地脚本、CI workflows、review/signature policy、GitHub required checks 或同类机制把它执行出来。它关注的是 gate contract，而不是某一门具体技术。

这个 Topic 用来回答“仓库怎样防止低质量或不完整的改动穿过默认分支”。它通常会和 PR label release、Release failure notification、React app 或 Rust web service 一起出现，但不替代这些 Topic：相邻 Topic 解释要验证什么，Quality gates 解释这些验证怎样被组织成不可跳过的 merge/readiness contract（projects/codex-vibe-monitor.md、projects/octo-rill.md）。当 gate 需要 release-impact 或 persistent-state evidence 时，它只 enforce evidence 的存在、格式与 waiver；兼容性和迁移政策仍属于 SemVer change governance 与 Persistent-state migrations。

当仓库里存在 .github/quality-gates.json、受保护分支规则、显式的 PR/main workflow 拆分、review policy、signed commits 要求、或 project snapshot 已把这些门禁写成当前事实时使用。命中条件不是“有 CI”，而是仓库已经定义了哪些检查必须通过、哪些行为不能绕过。

如果一个改动会改变 required checks、PR/main workflow 拆分、review/signature policy、merge-readiness 规则、waiver 机制、worktree/bootstrap smoke、或 gate 失败时的处理路径，就应该命中 Quality gates。若仓库只有零散测试 workflow，但没有明确 merge contract、没有 required-check 语义、也没有项目快照记录这些策略，则不应抬成这个 Topic（projects/codex-vibe-monitor.md、projects/octo-rill.md、projects/kaisoumail.md）。

• repo-local quality policy 应是 source of truth；GitHub UI state 只是要对齐的执行面，而不是唯一事实来源（projects/codex-vibe-monitor.md、projects/octo-rill.md）。
• 默认把默认分支视为 PR-only，直接 push 或绕过 required checks 必须是显式声明的例外，而不是隐性习惯（projects/flux-purr.md）。
• PR gate 和 main/release gate 要分层。前者阻止不完整改动进入默认分支，后者验证 merge 后或 release 前的系统行为；两者混成一个 workflow 时，维护者往往不知道失败应该在什么阶段被拦下（projects/kaisoumail.md、projects/codex-vibe-monitor.md）。
• gate 名称、required checks、review/signature policy 和 waiver 入口都要写在知识库里。只记录“有 CI”没有意义，必须写清哪些 check 名真的构成 merge contract（projects/octo-rill.md、projects/mains-aegis.md）。
• 需要 version-impact 或 durable-state migration evidence 的 gate，应明确检查 verified classification、migration validation 或已有 waiver；不得从 diff、workflow 或 gate green status 自行推导 compatibility policy（skills/style-playbook/references/topics/semver-change-governance/TOPIC.md、skills/style-playbook/references/topics/persistent-state-migrations/TOPIC.md）。
• 对多 surface 仓库，质量门禁必须覆盖真正的交付面，而不是只覆盖最容易跑的一层。设备 mono-repo 要同时覆盖 firmware/web/release；控制台类服务要同时覆盖 Rust、Web、Storybook、e2e 或 release intent（projects/flux-purr.md、projects/proxy-broker.md）。
• 对命中 React app Topic 的 Web React 任务，本地质量反馈与 PR merge gate 要分层：pre-commit 对 staged React 文件执行 React Doctor，CI 对 changed React 文件执行。比较 base/head、文件后缀、删除与重命名、生成目录排除、package 归属及显式输入遵循 skills/style-playbook/references/topics/react-app/TOPIC.md，报告所选文件的全部诊断，不以 --scope changed 仅拦新增问题代替文件范围契约。
• React Doctor 必须先成功计算相关文件集合，Git diff、base 解析或范围计算失败即阻断；集合为空时跳过并通过，不要求 Doctor、依赖、锁文件或配置可执行。集合非空时，依赖、锁文件、配置或命令无法执行属于 gate failure，必须 fail-closed；执行成功后 error 阻断提交和 merge，warning 保持可见但不阻断。接入复用现有 hook 管理器和项目锁定版本，不使用 npx react-doctor@latest 或 hook 内临时联网安装；monorepo 只检查受影响的 React package，多交付面项目只覆盖 React UI。
• CI 默认将 React Doctor 放入现有 required job 的必经 step，Doctor 失败必须传播为 job 失败；没有合适载体时使用名称稳定且在 workflows 间唯一的独立 required job。不得使用 continue-on-error 或吞掉非零退出结果。空集合只使 Doctor step 跳过并通过，承载 job 仍执行原有验证并产出 check；不得以 workflow/job 的 paths filter 让 required check 缺席。
• 在目标项目版本化的门禁配置或文档中记录承载 React Doctor 的实际 check 名，并通过托管平台 API/UI 核对目标分支 protection/ruleset 确实将该 check 设为 required。只看到 workflow 或 green job 不构成 required 的证据；权限、接口或分支规则无法核验时明确记录“未验证”，不能宣称已 enforce（https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches）。
• React Doctor 只负责 React-specific 质量信号，不替代 typecheck、build、单元/集成/e2e 测试、Storybook、Playwright、后端、固件或其他交付面检查；这些检查仍需由各自 Topic 和 gate contract 明确。
• React Doctor 规则例外必须通过版本化 doctor.config.* 审计；优先 doctor.config.ts，已有 .jsonc 可保留，以对应规则配置旁的注释记录规则、理由、影响范围和复核日期，机器对象仅使用官方支持的字段。合法格式与示例由 skills/style-playbook/references/topics/react-app/TOPIC.md 说明；本地命令参数静默绕过不构成可接受的 waiver。
• worktree/bootstrap 类 gate 很有价值，因为它验证“新环境能否按文档恢复工作”，不是只验证当前维护者机器刚好能跑（projects/octo-rill.md）。
• workflow failure notification 也应有 repo-local contract gate：对 expected-success workflow 做 exact classification，验证 generic/Release route、notification exclusions、trusted default-branch checkout 和 failure conclusion guard；Dockrev 将该检查挂在 CI (PR) 的 Lint & Checks job 中（projects/dockrev.md）。

• projects/codex-vibe-monitor.md：把 .github/quality-gates.json、PR/main/release 拆分和 review policy 都写成了显式 contract，是“门禁即产品规则”的强样本。
• projects/octo-rill.md：除了常规 CI/release 之外，还保留 test:worktree-bootstrap，适合说明质量门禁不只是测试，还包括环境恢复能力。
• projects/flux-purr.md：设备 mono-repo 需要 firmware/web/release 多条门禁同时成立，适合说明“单一 green check 不等于可合并”。
• projects/dockrev.md：把 PR、Docs Pages、release preparation/completion、Release 和 review gate 拆开，并用 .github/scripts/test_workflow_failure_notification_contract.py 防止 expected-success allowlist 漂移，适合说明通知路径本身也是可审计质量门禁。
• projects/kaisoumail.md：Cloudflare 多 surface 系统把 CI、deploy、docs 和 release 拆开，适合说明多交付面仓库的 gate 分层。
• projects/isolappurr-usb-hub.md：硬件 mono-repo 的 firmware、web、desktop、Pages 和 merge-queue gate 需要同时保持可见，适合说明多交付面不能只凭一条构建判断 readiness。
• projects/mains-aegis.md：docs/quality-gates.md 证明门禁可以被项目文档显式声明，而不只能隐含在 GitHub workflow 里。
• skills/policies/semver-change-governance/SKILL.md：定义 gate 消费的 verified version-impact classification，不规定 enforcement mechanics。
• skills/policies/persistent-state-migrations/SKILL.md：定义 gate 可要求的 state compatibility/migration evidence，不规定 required-check 或 waiver mechanics。
• skills/style-playbook/references/topics/markdown-style/TOPIC.md 与 skills/policies/markdown-style/SKILL.md：规定 Markdown 自然段排版、部分暂存自动修复和匹配的全仓检查；Quality gates 负责将该检查纳入既有 PR/main 门禁，不改变排版契约。

• 只写“有 CI”不写 required checks、review policy 或 main/release 分层，会让 Topic 失去判别力。
• 把 Quality gates 当成整个仓库的总括标签，忽略 PR label release、React app、Release failure notification 等相邻 Topic，会让后续 Agent 不知道真正应该验证的是 runtime、协议、UI 还是交付链路。
• gate 只存在于 GitHub UI，不存在 checked-in 文档或配置，会让仓库 truth 无法在本地复盘，也难以迁移到新仓或新默认分支。
• 把所有验证都塞进一个 workflow，会让失败语义混乱：维护者不知道这是 PR gate、release gate、deploy gate 还是通知链路坏了。
• 默认分支保护和 required checks 不一致时，门禁会从“规则”退化成“建议”；Topic 回答里必须显式检查这一点，而不是假设 workflow 存在就会被 GitHub 强制。
• 只验证业务 workflow 的 exit status、不验证 failure notification classification，会让门禁失败变成静默运维事件；应把 allowlist、route 和通知安全边界纳入 PR contract test。
• 只把 React Doctor 放进本地 hook 而没有 CI required check，会让合并路径绕过 React error；本地反馈和 CI merge gate 必须同时存在且保持相同的结果语义。
• 把 React Doctor 的 warning 当成阻断，或在非空文件集合中把工具执行失败当成通过，会混淆 findings 与 gate failure；应保留 warning 仅报告和非空集合 fail-closed 的语义。空集合应在工具检查前跳过；Git/base/范围失败不能算作空集合。
• 只创建 Doctor workflow、允许 Doctor step 失败后继续、让空集合缺少 required check 或没有核对真实 protection/ruleset，会使规定的 merge gate 不生效；应核验稳定的实际 check 名、失败传播和分支规则，无法核验时报告“未验证”。
• 让 React Doctor 替代其他交付面检查，或让一个多交付面仓库只跑 React package，会造成质量门禁覆盖不足。

• projects/codex-vibe-monitor.md
• projects/flux-purr.md
• projects/dockrev.md
• projects/isolappurr-usb-hub.md
• projects/kaisoumail.md
• projects/mains-aegis.md
• projects/octo-rill.md
• projects/style-playbook-skills.md
• projects/televy-backup.md
• skills/style-playbook/references/data/topics/quality-gates.json
• skills/style-playbook/references/topics/semver-change-governance/TOPIC.md
• skills/style-playbook/references/topics/persistent-state-migrations/TOPIC.md
• skills/style-playbook/references/topics/markdown-style/TOPIC.md
• skills/style-playbook/references/topics/react-app/TOPIC.md
• https://github.com/millionco/react-doctor
• https://react.doctor/docs/getting-started/install-for-coding-agents
• https://www.react.doctor/docs/reference/cli-reference
• https://www.react.doctor/docs/configuration/config-files
• https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches