Puerta de conformidad

La puerta de conformidad en src/apothem/conformity/gate.py ejecuta la fracción mecánica de la puerta de pre-emisión de quince barras (M1-M15) contra cada artefacto que redacta el operador.

Los comandos de esta página suponen un checkout de Apothem, así que antepón PYTHONPATH=src a cada comando que ejecutes. Tras una instalación con script, usa PYTHONPATH="$HOME/.apothem/src" en lugar de PYTHONPATH=src.

Ejecutar la puertaCopy Anchor Link

La puerta es consultiva de forma predeterminada: informa los hallazgos y sale con 0, de modo que una ejecución local nunca te bloquea. Agrega --strict (o establece APOTHEM_CONFORMITY_STRICT=1) para salir con un código distinto de cero ante un hallazgo bloqueante — el modo que usan CI y pre-commit para hacer fallar un cambio que incumple.

# 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 salida: 0 limpio (o consultivo), 2 un bloqueo por hallazgos en modo estricto, 3 un error de uso: un indicador o un nombre de validador desconocido, un archivo que no existe o un directorio raíz que no existe. --help imprime el uso completo y sale con 0. Cada validador independiente acepta el mismo --help y sale con 3 ante un indicador desconocido o una raíz faltante.

Una raíz relativa como . se resuelve a una ruta absoluta antes de que se ejecute cualquier validador, de modo que --all . y --all "$PWD" inspeccionan el mismo árbol. Cada validador informa inspected — cuántos destinos examinó — y --all copia ese recuento en cada entrada del resultado. Un validador que no inspeccionó nada informa passed: false, de modo que un directorio de trabajo equivocado no puede pasar en silencio. Los dos validadores de suites de plan son una excepción: las suites de plan residen en el árbol .apothem/plans/, ignorado por git, así que informan empty_scope_expected: true en un checkout limpio y aun así pasan. Los validadores de flujos de trabajo hacen lo mismo cuando el proyecto todavía no tiene un directorio .github/workflows/, y el validador de asuntos de commit lo hace cuando la raíz no tiene historial de commits.

Seis validadores parten de la raíz del repositorio y buscan en todo el árbol los archivos que comprueban:

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

Estos omiten los checkouts de git anidados, como worktrees, submódulos y clones anidados, y omiten los directorios que contienen dependencias, entornos virtuales, cachés o resultados de compilación, como node_modules, venv y dist. La comprobación de planes extraviados de no-global-plans-grep también se detiene en un checkout anidado. Una ejecución de cualquiera de ellos informa sobre el checkout al que se apuntó y sobre nada más. Un validador que lee una carpeta fija, como naming-grep bajo src/apothem/, lee todo lo que hay debajo de esa carpeta.

Barras de la puertaCopy Anchor Link

Comprobaciones dirigidasCopy 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

Un validador por escritura recibe el archivo que debe comprobar, o --stdin para leer el contenido desde la entrada estándar; sin ninguno de los dos, espera entrada en la entrada estándar, así que pasa el archivo cuando lo ejecutes desde una terminal. Un validador independiente recibe un directorio raíz (el directorio actual cuando se omite). --list muestra a qué grupo pertenece cada validador.

El modo --hook (python -m apothem.conformity.gate --hook) es el punto de entrada que despacha el entorno: lee desde stdin una carga útil JSON de entrada de herramienta y ejecuta la cadena de comparadores por escritura contra la escritura pendiente. Esta es la forma que invoca el hook PreToolUse desplegado; rara vez lo llamas a mano.

El modo hook está limitado a un conjunto de directorios. Ejecuta la cadena de comparadores solo en las escrituras cuyo destino está dentro de alguno de ellos; una escritura fuera de todos los alcances termina de inmediato como un pase silencioso. Los valores predeterminados son dos raíces:

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

Establece APOTHEM_CONFORMITY_SCOPE en un directorio para reemplazarlos:

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

Un hook que parece no hacer nada suele deberse a un destino fuera de alcance más que a un fallo — compara primero el destino de la escritura con los alcances indicados arriba.

Integración con CICopy Anchor Link

El trabajo de calidad de .github/workflows/ci.yml ejecuta la puerta en modo estricto (python -m apothem.conformity.gate --all . --strict) en los push a main y en las pull requests a main que tocan las rutas que ese trabajo vigila. El flujo de trabajo independiente .github/workflows/conformity.yml ejecuta el barrido de fixtures (tests/conformity-scenarios/verify.py --strict).