Шлюз соответствия

Шлюз соответствия в 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-чекауты, такие как рабочие деревья (worktrees), подмодули и вложенные клоны, а также каталоги с зависимостями, виртуальными окружениями, кешами или результатами сборки, такие как node_modules, venv и dist. Проверка посторонних планов в no-global-plans-grep также останавливается на вложенном чекауте. Запуск любого из них сообщает о чекауте, на который он был направлен, и ни о чём другом. Валидатор, который читает одну фиксированную папку, например naming-grep в src/apothem/, читает всё, что находится ниже этой папки.

Пункты шлюза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

Валидатор per-write принимает проверяемый файл или --stdin, чтобы прочитать содержимое из стандартного ввода; без того и другого он ожидает ввод на стандартном вводе, поэтому при запуске из терминала передавайте файл. Автономный валидатор принимает корневой каталог (текущий каталог, если он опущен). --list показывает, к какой группе относится каждый валидатор.

Режим --hook (python -m apothem.conformity.gate --hook) — это точка входа, которую вызывает окружение: он читает из stdin полезную нагрузку JSON с входными данными инструмента и прогоняет ожидающую запись через цепочку сопоставителей per-write. Именно эту форму вызывает развёрнутый хук 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

Хук, который, по всей видимости, ничего не делает, обычно означает промах мимо области, а не сбой, — сначала сверьте цель записи с перечисленными выше областями.

Интеграция с CICopy Anchor Link

Задание quality в .github/workflows/ci.yml запускает шлюз в строгом режиме (python -m apothem.conformity.gate --all . --strict) при push в main и при pull request в main, затрагивающих пути, которые отслеживает это задание. Отдельный рабочий процесс .github/workflows/conformity.yml выполняет прогон фикстур (tests/conformity-scenarios/verify.py --strict).