Conformity gate

O conformity gate em src/apothem/conformity/gate.py executa a fração mecânica do portão de pré-emissão de quinze barras (M1-M15) contra cada artefato que o operador redige.

Os comandos desta página pressupõem um checkout do Apothem, então prefixe com PYTHONPATH=src cada um que você executar. Após uma instalação por script, use PYTHONPATH="$HOME/.apothem/src" no lugar de PYTHONPATH=src.

Executar o portãoCopy Anchor Link

O portão é consultivo por padrão: ele relata os achados e sai com 0, de modo que uma execução local nunca bloqueia você. Adicione --strict (ou defina APOTHEM_CONFORMITY_STRICT=1) para sair com código diferente de zero diante de um achado bloqueante — o modo que o CI e o pre-commit usam para fazer falhar uma mudança que viola as regras.

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

Códigos de saída: 0 limpo (ou consultivo), 2 um bloqueio por achados no modo estrito, 3 um erro de uso: um sinalizador ou nome de validador desconhecido, um arquivo que não existe ou um diretório raiz que não existe. --help imprime o uso completo e sai com 0. Todo validador independente aceita o mesmo --help e sai com 3 diante de um sinalizador desconhecido ou de uma raiz ausente.

Uma raiz relativa como . é resolvida para um caminho absoluto antes que qualquer validador seja executado, de modo que --all . e --all "$PWD" inspecionam a mesma árvore. Cada validador relata inspected — quantos alvos ele examinou — e --all copia essa contagem para cada entrada de resultado. Um validador que não inspecionou nada relata passed: false, de modo que um diretório de trabalho errado não pode passar silenciosamente. Os dois validadores de suíte de planejamento são uma exceção: as suítes de planejamento ficam na árvore .apothem/plans/, ignorada pelo git, então eles relatam empty_scope_expected: true em um checkout limpo e ainda assim passam. Os validadores de fluxo de trabalho fazem o mesmo quando o projeto ainda não tem um diretório .github/workflows/, e o validador de assunto de commit faz o mesmo quando a raiz não tem histórico de commits.

Seis validadores partem da raiz do repositório e buscam em toda a árvore os arquivos que verificam:

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

Eles ignoram checkouts git aninhados, como worktrees, submódulos e clones aninhados, e ignoram diretórios que guardam dependências, ambientes virtuais, caches ou saída de build, como node_modules, venv e dist. A verificação de planos perdidos em no-global-plans-grep também para em um checkout aninhado. Uma execução de qualquer um deles relata sobre o checkout para o qual foi apontada e sobre nada mais. Um validador que lê uma pasta fixa, como naming-grep sob src/apothem/, lê tudo abaixo dessa pasta.

Barras do portãoCopy Anchor Link

Verificações direcionadasCopy 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

Um validador por gravação recebe o arquivo a verificar, ou --stdin para ler o conteúdo da entrada padrão; sem nenhum dos dois, ele espera por entrada na entrada padrão, então passe o arquivo ao executá-lo a partir de um terminal. Um validador independente recebe um diretório raiz (o diretório atual, quando omitido). --list mostra a qual grupo cada validador pertence.

O modo --hook (python -m apothem.conformity.gate --hook) é o ponto de entrada despachado pelo harness: ele lê um payload JSON de entrada de ferramenta da stdin e executa a cadeia de matchers por gravação contra a gravação pendente. Essa é a forma que o hook PreToolUse implantado invoca; raramente você o chama manualmente.

O modo hook tem escopo limitado a um conjunto de diretórios. Ele executa a cadeia de matchers apenas em gravações cujo alvo esteja sob um deles; uma gravação fora de todos os escopos é encerrada antecipadamente com uma aprovação silenciosa. Os padrões são duas raízes:

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

Defina APOTHEM_CONFORMITY_SCOPE como um diretório para substituí-las:

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

Um hook que parece não fazer nada geralmente é um caso de alvo fora do escopo, e não uma falha — verifique primeiro o alvo da gravação em relação aos escopos acima.

Integração com CICopy Anchor Link

O job de qualidade em .github/workflows/ci.yml executa o portão em modo estrito (python -m apothem.conformity.gate --all . --strict) em pushes para main e em pull requests para main que alterem os caminhos que esse job monitora. O fluxo de trabalho separado .github/workflows/conformity.yml executa a varredura de fixtures (tests/conformity-scenarios/verify.py --strict).