Conformity Gate

The conformity gate at src/apothem/conformity/gate.py runs the mechanical fraction of the fifteen-bar pre-emission gate (M1-M15) against every artifact the operator authors.

The commands on this page assume an Apothem checkout, so prefix each one you run with PYTHONPATH=src. After a script install, use PYTHONPATH="$HOME/.apothem/src" in place of PYTHONPATH=src.

Running the gateCopy Anchor Link

The gate is advisory by default: it reports findings and exits 0, so a local run never blocks you. Add --strict (or set APOTHEM_CONFORMITY_STRICT=1) to exit non-zero on a blocking finding — the mode CI and pre-commit use to fail a violating change.

# 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 .

Exit codes: 0 clean (or advisory), 2 a strict findings-block, 3 a usage error: an unknown flag or validator name, a file that does not exist, or a root directory that does not exist. --help prints the full usage and exits 0. Every standalone validator accepts the same --help and exits 3 on an unknown flag or a missing root.

A relative root such as . is resolved to an absolute path before any validator runs, so --all . and --all "$PWD" inspect the same tree. Each validator reports inspected — how many targets it examined — and --all copies that count into every result entry. A validator that inspected nothing reports passed: false, so a wrong working directory cannot pass silently. The two plan-suite validators are one exception: plan suites live in the gitignored .apothem/plans/ tree, so they report empty_scope_expected: true on a clean checkout and still pass. The workflow validators do the same when the project has no .github/workflows/ directory yet, and the commit-subject validator does when the root has no commit history.

Six validators start at the repository root and search the whole tree for the files they check:

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

These skip nested git checkouts, such as worktrees, submodules and nested clones, and skip directories that hold dependencies, virtual environments, caches or build output, such as node_modules, venv and dist. The stray-plans check in no-global-plans-grep also stops at a nested checkout. A run of any of these reports on the checkout it was pointed at and on nothing else. A validator that reads one fixed folder, such as naming-grep under src/apothem/, reads everything below that folder.

Gate barsCopy Anchor Link

Targeted checksCopy 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

A per-write validator takes the file to check, or --stdin to read the content from standard input; with neither it waits for input on standard input, so pass the file when you run it from a terminal. A standalone validator takes a root directory (the current directory when omitted). --list shows which group each validator belongs to.

--hook mode (python -m apothem.conformity.gate --hook) is the harness-dispatched entry point: it reads a tool-input JSON payload from stdin and runs the per-write matcher chain against the pending write. This is the form the deployed PreToolUse hook invokes; you rarely call it by hand.

Hook mode is scoped to a set of directories. It runs the matcher chain only on writes whose target falls under one of them; a write outside every scope short-circuits to a silent pass. The defaults are two roots:

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

Set APOTHEM_CONFORMITY_SCOPE to a directory to replace them:

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

A hook that appears to do nothing is usually a scope miss rather than a failure — check the write's target against the scopes above first.

CI integrationCopy Anchor Link

The quality job in .github/workflows/ci.yml runs the gate in strict mode (python -m apothem.conformity.gate --all . --strict) on pushes to main and on pull requests to main that touch the paths that job watches. The separate .github/workflows/conformity.yml workflow runs the fixture sweep (tests/conformity-scenarios/verify.py --strict).