적합성 게이트

src/apothem/conformity/gate.py에 있는 적합성 게이트는 운영자가 작성하는 모든 아티팩트에 대해 15개 막대 사전 방출 게이트(M1-M15)의 기계적 부분을 실행합니다.

이 페이지의 명령은 Apothem 체크아웃을 전제로 하므로, 실행하는 각 명령 앞에 PYTHONPATH=src를 붙이세요. 스크립트로 설치한 뒤에는 PYTHONPATH=src 대신 PYTHONPATH="$HOME/.apothem/src"를 사용하세요.

게이트 실행Copy Anchor Link

게이트는 기본적으로 권고 모드입니다. 발견 사항을 보고하고 0으로 종료하므로, 로컬 실행이 여러분을 막는 일은 절대 없습니다. 차단 수준의 발견 사항이 있을 때 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는 strict 모드의 발견 사항 차단, 3은 사용법 오류로, 알 수 없는 플래그나 검증기 이름, 존재하지 않는 파일, 또는 존재하지 않는 루트 디렉터리입니다. --help는 전체 사용법을 출력하고 0으로 종료합니다. 모든 독립 실행형 검증기는 같은 --help를 받아들이며, 알 수 없는 플래그나 누락된 루트에 대해 3으로 종료합니다.

. 같은 상대 루트는 어떤 검증기든 실행되기 전에 절대 경로로 해석되므로, --all .과 --all "$PWD"는 같은 트리를 검사합니다. 각 검증기는 검사한 대상의 수인 inspected를 보고하며, --all은 그 수를 모든 결과 항목에 복사합니다. 아무것도 검사하지 않은 검증기는 passed: false를 보고하므로, 잘못된 작업 디렉터리가 조용히 통과할 수 없습니다. 두 플랜 스위트 검증기는 예외 중 하나입니다. 플랜 스위트는 gitignore된 .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 대상 풀 리퀘스트에서 게이트를 strict 모드로 실행합니다(python -m apothem.conformity.gate --all . --strict). 별도의 .github/workflows/conformity.yml 워크플로는 픽스처 스위프(tests/conformity-scenarios/verify.py --strict)를 실행합니다.