적합성 게이트
적합성 게이트
Apothem 적합성 게이트 — 방출되는 모든 아티팩트가 통과해야 하는 15개 막대 사전 방출 게이트(M1-M15)의 기계적 부분.
15개 막대
| 막대 | ID | 맨데이트 | 검사 분류 | 실패 → 조치 |
|---|---|---|---|---|
| 1 | M1 | 호스트 프로젝트 비종속성 | 추론형 | 호스트 관례에 맞게 수정 |
| 2 | M2 | 편집 규율(공개 원장) | 추론형 | 공개 표시 추가 |
| 3 | M3 | 열 가지 품질 차원 | 기계형 + 추론형 | 실패한 차원을 수정 |
| 4 | M4 | 자기 적용(검증 블록 존재) | 추론형 | 검증 블록 기록 |
| 5 | M5 | 권한 원칙(날조된 신원 / 엔드포인트 / 시크릿 없음) | 기계형 | 질의로 전달 |
| 6 | M6 | 전문성 반영(드러난 공백) | 추론형 | 공백을 드러내고 개선 사항 인용 |
| 7 | M7 | 선택지 주석(Recommended 표시 + 결정 요인 근거) | 기계형 | 선택지 집합에 주석 달기 |
| 8 | M8 | 확정성(규범적 산문에 얼버무림 없음) | 기계형 | 얼버무림을 조건문으로 격상 |
| 9 | M9 | 시각적 활용(구조적 주제에는 다이어그램 포함) | 기계형 + 추론형 | 다이어그램 작성 / 갱신 |
| 10 | M10 | 양방향 바인딩(상호 역방향 포인터가 닫혀 있음) | 기계형 | 반쪽 간선 닫기 |
| 11 | M11 | 애자일 스프린트(목표 / 백로그 / DoR / DoD / 검토 / 회고) | 추론형 | 스프린트로 재구성 |
| 12 | M12 | 단계 보고 및 표준 레이아웃 | 기계형 + 추론형 | 롤업을 작성하고 표준 레이아웃으로 재배치 |
| 13 | M13 | 코드 장인 정신(린트 / 포맷 / 타입 검사; 매직 넘버; bare-except) | 기계형 | 언어별 코드 작성 규칙 적용 |
| 14 | M14 | 체계성(상류 / 하류 / 동료 / 집행자 선언) | 기계형 + 추론형 | 선언하고 레지스트리에 색인 |
| 15 | M15 | 프로덕션 준비(테스트 + 문서 + CHANGELOG + 적합한 커밋 + CI 녹색 + semver 안정성) | 기계형 + 추론형 | 누락된 표면 추가 |
게이트는 기계로 검사할 수 있는 검증기만 실행합니다. 추론형 막대가 요구하는 추론 판단과, 기계형 + 추론형 막대 각각의 추론 절반은 검토 단계에서 평가됩니다.
심각도 단계
게이트에는 치명, 중요, 권고로 나뉘는 등급 체계가 없고, 두 건의 발견 사항이라는 임계값도 없습니다. --strict(또는 APOTHEM_CONFORMITY_STRICT=1)가 없으면 게이트는 발견 사항을 보고하고 0으로 종료합니다. --strict를 지정하면 단일 파일 또는 훅 검사는 어떤 매처든 실패할 때 2로 종료하고, 코퍼스 실행(--all 또는 --all-perwrite)은 차단 검증기 또는 매처가 실패할 때 2로 종료합니다. 권고 발견 사항은 보고만 합니다. 설치된 Write/Edit 훅은 --strict를 전달하지 않으므로, 그 환경에 APOTHEM_CONFORMITY_STRICT=1이 설정되어 있지 않은 한 발견 사항을 보고하고 쓰기는 그대로 진행됩니다.
검증기
기계적 부분은 src/apothem/conformity/에 있으며, src/apothem/conformity/gate.py가 이를 조율합니다.
각 검증기는 다음 세 가지 방식 중 하나로 실행됩니다.
- per-write: 보류 중인 모든 쓰기마다(
--hook), 또는--all-perwrite로 추적되는 모든 파일에 대해 실행합니다. - standalone:
--all로 저장소 전체에 걸쳐 실행하거나,--check <name>으로 하나씩 실행합니다. - change-set: 스테이징된 diff를 대상으로 하며, 게이트를 거치지 않고
python -m apothem.conformity.semver_stability_grep --staged로 직접 실행합니다.
아래 표는 검증기 모듈에서 생성됩니다.
The conformity package ships 54 validators: 22 per-write, 31 standalone and 1 change-set. The gate registers the per-write and standalone ones.
| Validator | Runs | Rule anchor | What it checks |
|---|---|---|---|
agent-capability-grep | standalone | agent-capability-discipline (per-harness capability matrix) | Verify every harness declares its agentic-capability matrix. |
agents-md-coverage-grep | standalone | rules/agents-md-convention.md | Flag stale agent-companion files under the root-only AGENTS.md convention. |
agnosticism-grep | standalone | rules/agnostic-posture.md §3 (harness neutrality) + §1 (default-off) | Flag harness bias and re-introduced enforcement presets in shipped surfaces. |
always-on-budget-grep | per-write | D1 token-budget-discipline §Always-on body budget | Body-budget conformity matcher for always-on rules. Pointed at a rules directory it also holds the loaded always-on set and the rule index to byte ceilings. |
bare-except-grep | per-write | M13.3 error handling | Flag bare except clauses without typed exceptions or re-raise. |
binding-five-direction-grep | standalone | M10 bidirectional-binding §1 (five-direction Bindings section) | Require the five-direction Bindings section on every rule, command, agent, and skill. |
binding-reciprocity-corpus-grep | standalone | M10 bidirectional-binding §2 (↔ self-reciprocal) | Cross-file binding-reciprocity corpus walk — the ↔-symmetric half-edge check. |
binding-reciprocity-grep | per-write | M10 bidirectional-binding §Notation | Flag binding declarations using non-canonical arrow notation. |
brand-mark-grep | per-write | rules/plain-language.md (brand-mark display/identifier casing) | Flag brand-mark display/identifier form drift on brand-touched surfaces. |
commented-out-code-grep | per-write | M13.1 why-not-what comments | Flag substantial commented-out code blocks left in source. |
completion-claim-grep | per-write | rules/session-closure.md (verifiable-close output honesty) | Flag unsupported completion / guarantee claims in cohort prose. |
conventional-commit-grep | standalone | CLAUDE.md Coding Conventions — Conventional Commits | Flag HEAD commit messages that drift from the Conventional-Commits grammar. |
copilot-instructions-presence-grep | per-write | — | GitHub Copilot surface presence check. |
cross-platform-matrix-grep | standalone | cross-platform OS x Python CI matrix | Verify CI declares a cross-platform OS x Python matrix. |
determinism-grep | standalone | rules/determinism.md | Prove every command and skill surface has a deterministic output shape. |
diagram-staleness-grep | per-write | M9 visual-leverage §Fidelity | Flag diagrams whose verification date is missing or stale. |
dynamism-grep | standalone | rules/dynamism.md (static-version embeds) | Flag static-string version embeds in dynamism-required surfaces. |
editorconfig-presence-grep | standalone | supply-chain SOTA-rigor §editorconfig | Verify a canonical .editorconfig is present at the project root. |
file-header-grep | per-write | — | Authorship-header presence and canonical-form check. |
freshness-token-grep | standalone | rules/freshness-facade.md | Flag freshness-narrative phrases on shipped public surfaces. |
frontmatter-grep | per-write | the per-class frontmatter JSON Schemas (src/apothem/schemas/) | Validate per-artifact-class YAML frontmatter against required-key sets. |
frontmatter-value-grep | standalone | per-class JSON Schema enum/pattern value constraints | Validate frontmatter VALUES against the per-class JSON Schema enum/pattern constraints. |
gate-evidence-grep | standalone | commands/plan-execute.md Gate evidence; rules/pre-emission-gate-bars.md section 2 (attestation schema) | Advisory: flag plan-suite gate claims that lack a command, an exit status or output, and a HEAD SHA beside them, and fifteen-bar attestations that omit a field of the rule's schema. |
gitattributes-presence-grep | standalone | supply-chain .gitattributes contract | Verify the repo-root .gitattributes carries the canonical contract. |
harden-runner-grep | standalone | harden-runner egress baseline | Verify every workflow job opens with a conformant harden-runner step. |
hedging-grep | per-write | M8 definitiveness §Hedging | Flag hedging vocabulary in prescriptive contexts. |
license-author-consistency-grep | per-write | — | LICENSE author-identity presence check. |
link-check | per-write | rules/code-craft-markdown.md §6 Link Discipline | Validate Markdown internal links against the on-disk reference graph. |
magic-number-grep | per-write | M13.10 magic numbers | Flag magic numbers in source code. |
multi-surface-coherence-grep | per-write | — | Shared-claim coherence across AI-conventions surfaces. |
naming-grep | standalone | CLAUDE.md Coding Conventions (kebab-case naming) | Validate filesystem paths against the canonical naming convention. |
no-global-plans-grep | standalone | CLAUDE.md Plans Discipline (no global plans) | Walk the git index for tracked plans paths; fail when found. |
no-toplevel-docs-grep | standalone | single-source-of-truth (docs live in site/, not root docs/) | Fail when a top-level docs/ directory exists at the repository root. |
oidc-trusted-publishing-grep | standalone | OIDC trusted publishing | Verify release workflows use OIDC trusted publishing. |
option-annotation-grep | per-write | M7 option-annotation (H6 per-option bind) | Enforce the per-option Recommended label-to-body bind (H6). |
orphan-output-grep | per-write | M12 canonical-layout + M14 systemicity | Flag artifacts emitted to non-canonical locations or without provenance. |
permissions-minimum-scope-grep | standalone | minimum-scope workflow permissions | Verify every GitHub Actions workflow declares a minimum-scope permissions: block. |
plain-language-grep | standalone | rules/plain-language.md — user-facing prose | Flag mechanistic / harness-internal vocabulary in user-facing prose. |
plan-next-step-consistency-grep | standalone | rules/recommend-next-step.md | Advisory: flag plan-suite infra files whose Recommended-Next-Step footer drifts from the suite's recorded next pipeline stage. |
plan-suite-structure-grep | standalone | context-management-scratch 2 (suite-locality + closed vocab) + canonical-layout-reporting-tiers 2.1 (numeric-prefix discipline) | Validate plan-suite structure: suite-locality, closed vocab, numeric prefix. |
plans-discipline-language-grep | standalone | CLAUDE.md Plans Discipline (multi-surface language) | Verify the canonical Plans Discipline language reaches every required surface. |
production-ready-pr-grep | per-write | M15 production-ready §Same-change-set | Flag commits whose change-set lacks the production-ready four-class shape. |
recommend-next-step-grep | standalone | rules/recommend-next-step.md | Verify every command file carries a ## Recommended Next Step block. |
redundancy-grep | standalone | rules/operational-mandates.md §CM-7 coherent-product non-redundancy | Flag substantively-duplicated paragraphs across the governed corpus. |
reference-token-grep | standalone | rules/own-voice-reimplementation.md | Flag leaked reference-platform branding tokens on authored surfaces. |
registry-capability-consistency-grep | standalone | rules/agent-capability-discipline.md — registry capability cells backed by evidence | Flag registry capability cells not backed by install / materializer / projection evidence. |
secret-leak-grep | per-write | M13.8 security + M15 production-ready | Block emission of artifacts containing hardcoded credentials. |
semver-stability-grep | change-set | M15 semver-stability | Semver stability matcher (M15 mechanical fraction). |
smoke-install-grep | standalone | production-ready section 8.1 paired install scripts | Smoke-test the paired install scripts at the repository root. |
static-version-grep | standalone | rules/dynamism.md §static-version-resolution | Verify version-bearing sites resolve dynamically, not as static literals. |
token-efficiency-grep | per-write | clean-room-generation §5 + token-efficiency-rewrite | Flag filler phrases, throat-clearing openers, and content-free qualifiers. |
unpinned-action-grep | per-write | M15 production-ready §Supply-chain | Flag GitHub Actions workflows that pin actions to mutable refs. |
user-confirm-grep | per-write | M5 authority-inquiry §10 | Block emission of artifacts containing unresolved authority placeholders. |
workflow-concurrency-grep | standalone | workflow concurrency + per-job timeouts | Enforce concurrency + per-job timeout discipline on GitHub workflows. |
게이트 실행
설치된 하니스에서는 게이트가 자동으로 실행됩니다. Claude Code의
settings.json은 게이트를 PreToolUse 훅으로 연결하며, 이 훅은 모든
Write/Edit 전에 ~/.claude/.apothem/support/conformity/gate.py에 머티리얼라이즈된
사본을 호출합니다. 이때 게이트는 훅 범위에 속한 쓰기만 검사하며, 범위 밖의 쓰기는
조용히 통과합니다. 범위는 적합성 게이트 실행에
나와 있습니다. 소스 체크아웃에서는 모듈 형식이 같은 코드를 실행합니다. 아래의 각
python 명령 앞에 PYTHONPATH=src를 붙이세요. 게이트는 기본적으로 권고
모드입니다. 발견 사항을 보고하고 0으로 종료합니다. 차단 수준의 발견 사항이 있을
때 2로 종료하려면 --strict를 추가하세요. 알 수 없는 검증기 이름은 3으로
종료합니다.
# Every standalone validator across the repository:
python -m apothem.conformity.gate --all .
# The same sweep, failing on a blocking finding (the CI form):
python -m apothem.conformity.gate --all --strict .
# Every per-write validator against every tracked file:
python -m apothem.conformity.gate --all-perwrite .
# One validator by name (names come from --list):
python -m apothem.conformity.gate --check naming-grep .
# List every registered validator as JSON:
python -m apothem.conformity.gate --list
# Single-file dispatch (mimics the PreToolUse hook):
echo '{"tool_input": {"file_path": "path/to/file", "content": "..."}}' \
| python -m apothem.conformity.gate --hookpython -m apothem.conformity.gate --help는 사용법 요약을 출력합니다.
전체 절차는 적합성 게이트 실행을 참조하세요.
참조
- 사전 방출 게이트 레지스트리 — 표준 막대 정의
- 대외 적합성 레지스트리 — M1-M15의 상세 의미
- 횡단 맨데이트 — 맨데이트의 진실의 원천
- 성능 규율 — 분류별 런타임 예산