10 · 自动门禁

从 pre-commit 到 CI 的检查链

关键文件lefthook.ymlscripts/run-gates.tsscripts/verify-*.tsscripts/gen-*.ts.github/workflows/ci.yml

每一站各司其职。git hook 刻意保持很窄，只做能自动修复或很快的检查。推送前由开发者（或 Agent）按改动面挑证据。穷尽的覆盖和多平台矩阵交给 CI。评审只看机器无法判断的语义问题。

run-gates：门禁聚合器

scripts/run-gates.ts 把几十个检查组织成聚合模式：本地常用的 doc-sync、hygiene、doc-quick（即 pnpm run test:docs），以及 CI 用的 ci-static、ci-coverage、ci-snapshot、ci-windows-* 等。每个门禁可以声明依赖，并发数有上限（每个文档门禁都会构建完整的 ts.Program，不设上限会耗尽内存）。被中止的门禁即使退出码为 0 也不会报告为通过。

verify-* 脚本分类

目的	脚本
类型与代码	verify-no-unknown-casts、verify-export-jsdoc、verify-no-top-level-await、verify-no-bare-dispatcher、verify-plugin-record-callers
措辞与格式	verify-concrete-terms、verify-md-wrap、verify-doc-budgets、verify-mermaid
文档与代码一致	verify-type-equiv、verify-doc-refs、verify-md-links、verify-subsystem-pages、verify-package-readme-model-experience、verify-package-readme-limitations、verify-package-readme-summaries
架构与依赖隔离	verify-default-product-isolation、verify-product-use、verify-package-dependencies、verify-optional-dependency-imports、verify-runtime-closure、verify-config-source-ownership、verify-cordis-config
界面文案	verify-client-ui-i18n
决策与升级记录	verify-agent-note-format、verify-agent-note-classification、verify-archived-agent-notes、verify-upgrade-guides
引用卫生	verify-repository-references（拒绝引用 commit 哈希）、verify-public-repository-links
生成物新鲜度	gen-tool-catalog、gen-config-catalog、gen-cli-help、gen-module-graph 等，均以 --check 模式运行

门禁自身的规则

• 能机器检查的不变量要接入一个实际执行的顶层门禁，并证明每条修改过的验收路径会拒绝一个非法用例。
• 用范围窄、有理由的例外，不要全局关闭一条规则。
• 门禁脚本做语法感知的发现，防止扫描语料意外变空或被缩小，并测试每种被纳入和被排除的形式（scripts/AGENTS.md）。
• lint 规则本身也有测试：oxlint-contract.spec.ts、lint-rule-fingerprint.spec.ts。