合规闸门

位于 src/apothem/conformity/gate.py 的合规闸门会针对操作者编写的每个工件，运行十五道预发布闸门关卡（M1-M15）中的机械部分。

本页上的命令假定位于 Apothem 检出中，因此请在你运行的每条命令前加上 PYTHONPATH=src。脚本安装之后，请使用 PYTHONPATH="$HOME/.apothem/src" 替代 PYTHONPATH=src。

运行闸门Copy Anchor Link

闸门默认为建议性：它报告发现项并以 0 退出，因此本地运行绝不会阻塞你。添加 --strict（或设置 APOTHEM_CONFORMITY_STRICT=1），即可在出现阻断性发现项时以非零状态退出——CI 和 pre-commit 正是使用这种模式让违规的变更失败。

# Advisory: report every validator's findings across the repo, exit 0
PYTHONPATH=src python -m apothem.conformity.gate --all .

# Strict: exit non-zero (code 2) when a blocking finding is present
PYTHONPATH=src python -m apothem.conformity.gate --all --strict .

退出码：0 表示干净（或建议性模式），2 表示严格模式下的发现项阻断，3 表示用法错误：未知的标志或校验器名称、不存在的文件，或不存在的根目录。--help 打印完整用法并以 0 退出。每个独立校验器都接受同样的 --help，并在遇到未知标志或缺失的根目录时以 3 退出。

诸如 . 的相对根目录会在任何校验器运行之前被解析为绝对路径，因此 --all . 和 --all "$PWD" 检查的是同一棵树。每个校验器都会报告 inspected——即它检查了多少个目标——而 --all 会将该计数复制到每个结果条目中。未检查任何内容的校验器会报告 passed: false，因此错误的工作目录不会无声地通过。两个计划套件校验器是其中一种例外：计划套件位于被 git 忽略的 .apothem/plans/ 树中，因此它们在干净的检出上报告 empty_scope_expected: true 并仍然通过。当项目还没有 .github/workflows/ 目录时，工作流校验器也会这样做；当根目录没有提交历史时，提交主题校验器也会这样做。

有六个校验器从仓库根目录开始，在整棵树中搜索它们要检查的文件：

agents-md-coverage-grep
agnosticism-grep
dynamism-grep
freshness-token-grep
plain-language-grep
reference-token-grep

这些校验器会跳过嵌套的 git 检出（例如工作树、子模块和嵌套克隆），也会跳过存放依赖项、虚拟环境、缓存或构建输出的目录（例如 node_modules、venv 和 dist）。no-global-plans-grep 中的游离计划检查同样会在嵌套检出处停止。运行其中任意一个校验器时，它只报告其所指向的那个检出，而不报告其他任何内容。读取某个固定文件夹的校验器（例如读取 src/apothem/ 的 naming-grep）会读取该文件夹之下的全部内容。

闸门关卡Copy Anchor Link

定向检查Copy Anchor Link

# List every registered validator
PYTHONPATH=src python -m apothem.conformity.gate --list

# Run one per-write validator against one file
PYTHONPATH=src python -m apothem.conformity.gate --check multi-surface-coherence src/apothem/rules/my-rule.md

# Run one standalone validator over a root directory
PYTHONPATH=src python -m apothem.conformity.gate --check naming-grep .

# Run every per-write validator against one file
PYTHONPATH=src python -m apothem.conformity.gate src/apothem/rules/my-rule.md

逐写入校验器接受要检查的文件，或者接受 --stdin 以从标准输入读取内容；两者都不提供时，它会等待标准输入上的输入，因此从终端运行时请传入该文件。独立校验器接受一个根目录（省略时为当前目录）。--list 会显示每个校验器所属的分组。

--hook 模式（python -m apothem.conformity.gate --hook）是由工具调度的入口点：它从 stdin 读取一个工具输入 JSON 载荷，并针对待处理的写入运行逐写入匹配器链。部署后的 PreToolUse 钩子调用的就是这种形式；你很少需要手动调用它。

钩子模式限定于一组目录。它只对目标位于其中某个目录之下的写入运行匹配器链；位于所有范围之外的写入会短路为无声通过。默认值是两个根目录：

~/.claude      Claude Code
$CODEX_HOME    Codex (~/.codex when CODEX_HOME is not set)

将 APOTHEM_CONFORMITY_SCOPE 设置为某个目录即可替换它们：

# Run the per-write matcher chain against one project tree instead
export APOTHEM_CONFORMITY_SCOPE=/path/to/project

看似什么都没做的钩子，通常是未命中范围，而不是故障——请先对照上述范围检查该写入的目标。

CI 集成Copy Anchor Link

.github/workflows/ci.yml 中的 quality 作业会在向 main 的推送上，以及在针对 main 且涉及该作业所监视路径的拉取请求上，以严格模式运行闸门（python -m apothem.conformity.gate --all . --strict）。独立的 .github/workflows/conformity.yml 工作流则运行夹具扫描（tests/conformity-scenarios/verify.py --strict）。