Konformitäts-Gate

Das Konformitäts-Gate unter src/apothem/conformity/gate.py führt den mechanischen Anteil des fünfzehnstufigen Pre-Emission-Gates (M1-M15) gegen jedes Artefakt aus, das der Operator verfasst.

Die Befehle auf dieser Seite setzen einen Apothem-Checkout voraus; stellen Sie daher jedem Befehl, den Sie ausführen, PYTHONPATH=src voran. Nach einer Skript-Installation verwenden Sie PYTHONPATH="$HOME/.apothem/src" anstelle von PYTHONPATH=src.

Das Gate ausführenCopy Anchor Link

Das Gate ist standardmäßig beratend: Es meldet Befunde und endet mit 0, sodass ein lokaler Lauf Sie niemals blockiert. Fügen Sie --strict hinzu (oder setzen Sie APOTHEM_CONFORMITY_STRICT=1), damit es bei einem blockierenden Befund mit einem Wert ungleich null endet — der Modus, den CI und pre-commit verwenden, um eine Änderung mit Verstößen scheitern zu lassen.

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

Exit-Codes: 0 sauber (oder beratend), 2 eine Blockierung durch Befunde im strikten Modus, 3 ein Nutzungsfehler: ein unbekanntes Flag oder ein unbekannter Validator-Name, eine Datei, die nicht existiert, oder ein Stammverzeichnis, das nicht existiert. --help gibt die vollständige Nutzung aus und endet mit 0. Jeder eigenständige Validator akzeptiert dasselbe --help und endet bei einem unbekannten Flag oder einem fehlenden Stammverzeichnis mit 3.

Ein relatives Stammverzeichnis wie . wird in einen absoluten Pfad aufgelöst, bevor irgendein Validator läuft, sodass --all . und --all "$PWD" denselben Baum untersuchen. Jeder Validator meldet inspected — wie viele Ziele er untersucht hat —, und --all kopiert diese Zahl in jeden Ergebniseintrag. Ein Validator, der nichts untersucht hat, meldet passed: false, sodass ein falsches Arbeitsverzeichnis nicht still bestehen kann. Die beiden Plan-Suite-Validatoren sind eine Ausnahme: Plan-Suites liegen im per gitignore ausgeschlossenen Baum .apothem/plans/, daher melden sie bei einem sauberen Checkout empty_scope_expected: true und bestehen dennoch. Die Workflow-Validatoren tun dasselbe, wenn das Projekt noch kein Verzeichnis .github/workflows/ hat, und der Commit-Subject-Validator, wenn das Stammverzeichnis keine Commit-Historie hat.

Sechs Validatoren beginnen im Wurzelverzeichnis des Repositorys und durchsuchen den gesamten Baum nach den Dateien, die sie prüfen:

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

Diese überspringen verschachtelte Git-Checkouts, etwa Worktrees, Submodule und verschachtelte Klone, und überspringen Verzeichnisse, die Abhängigkeiten, virtuelle Umgebungen, Caches oder Build-Ausgaben enthalten, etwa node_modules, venv und dist. Die Prüfung auf verirrte Pläne in no-global-plans-grep hält ebenfalls an einem verschachtelten Checkout an. Ein Lauf eines dieser Validatoren meldet Ergebnisse zu dem Checkout, auf den er gerichtet wurde, und zu nichts anderem. Ein Validator, der einen festen Ordner liest, etwa naming-grep unter src/apothem/, liest alles unterhalb dieses Ordners.

Gate-StufenCopy Anchor Link

Gezielte PrüfungenCopy 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

Ein Validator pro Schreibvorgang nimmt die zu prüfende Datei entgegen oder --stdin, um den Inhalt von der Standardeingabe zu lesen; ohne beides wartet er auf Eingaben über die Standardeingabe, übergeben Sie also die Datei, wenn Sie ihn aus einem Terminal ausführen. Ein eigenständiger Validator nimmt ein Stammverzeichnis entgegen (das aktuelle Verzeichnis, wenn es weggelassen wird). --list zeigt, zu welcher Gruppe jeder Validator gehört.

Der --hook-Modus (python -m apothem.conformity.gate --hook) ist der vom Harness aufgerufene Einstiegspunkt: Er liest eine JSON-Nutzlast mit der Tool-Eingabe von stdin und führt die Matcher-Kette pro Schreibvorgang gegen den ausstehenden Schreibvorgang aus. Dies ist die Form, die der bereitgestellte PreToolUse-Hook aufruft; Sie rufen sie selten von Hand auf.

Der Hook-Modus ist auf eine Menge von Verzeichnissen beschränkt. Er führt die Matcher-Kette nur bei Schreibvorgängen aus, deren Ziel unter eines davon fällt; ein Schreibvorgang außerhalb aller Geltungsbereiche wird sofort als stilles Bestehen abgeschlossen. Die Standardwerte sind zwei Stammverzeichnisse:

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

Setzen Sie APOTHEM_CONFORMITY_SCOPE auf ein Verzeichnis, um sie zu ersetzen:

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

Ein Hook, der scheinbar nichts tut, ist meist eher ein Treffer außerhalb des Geltungsbereichs als ein Fehler — prüfen Sie zuerst das Ziel des Schreibvorgangs gegen die oben genannten Geltungsbereiche.

CI-IntegrationCopy Anchor Link

Der Qualitätsjob in .github/workflows/ci.yml führt das Gate im Strict-Modus (python -m apothem.conformity.gate --all . --strict) bei Pushes auf main und bei Pull Requests auf main aus, die die Pfade berühren, die dieser Job überwacht. Der separate Workflow .github/workflows/conformity.yml führt den Fixture-Durchlauf aus (tests/conformity-scenarios/verify.py --strict).