COMPASS-Doku
ENDE

Prüfweg anhängen

Ein Prüfweg ist ein lesender Befehl, den COMPASS ausführen kann, um zu sehen, ob die Wirklichkeit noch zu einer Regel passt. Er urteilt nicht selbst — sein Lauf schreibt einen Fakt, und widerspricht dieser Fakt der Regel, an die er angehängt ist, entsteht eine Abweichung.

Anlegen

curl -sS -X POST "$COMPASS_URL/pruefwege" \
  -H "X-Compass-Key: $COMPASS_KEY_RW" -H "Content-Type: application/json" \
  -d '{"slug": "ci-timeout-grep", "typ": "grep",
       "befehl": "grep -r \"timeout-minutes: 20\" .github/workflows/",
       "erwartung": "mindestens ein Treffer",
       "laufumgebung": "host-ro"}'

typ ist eines von shell|sql|http|grep|mcp. laufumgebung ist eines von host-ro|wegwerf-container|backend-ro. 201 für einen neuen Slug; derselbe Aufruf mit demselben slug ist ein Upsert von titel/typ/befehl/erwartung/laufumgebung und liefert 200 — das letzte Lauf-Ergebnis bleibt unangetastet.

Die Befehls-Allowlist

befehl wird vor der Annahme gegen eine feste Liste erlaubter Präfixe geprüft und sofort verworfen, wenn er ein schreibendes Muster enthält — das verhindert, dass ein „Prüfweg" zu einem zweiten Schreibweg wird.

Erlaubte Präfixe: gh api, git ls-files, git rev-list, curl -s, psql -c "SELECT, grep, ls, cat, test -f, docker inspect, bash scripts/ops/, python3 scripts/ops/.

Verboten, wenn irgendwo im Befehl enthalten: >, rm, DELETE, UPDATE, INSERT, -X POST, git push, docker push. Bewusst kein bares push auf dieser Liste — das würde auch lesende Skripte blockieren, deren Name das Wort enthält (z. B. ein pre-push-*-Gate-Skript, aufgerufen über das scripts/ops/-Präfix).

Ein Befehl, der nicht auf der Allowlist steht oder eines dieser Muster enthält, wird mit 422 abgewiesen, bevor irgendetwas gespeichert wird.

An eine Regel anhängen

pruefweg_slug beim Schreiben der Aussage setzen, damit GET /warum/{sache} und die Abweichungsliste ihn finden:

curl -sS -X POST "$COMPASS_URL/aussagen" \
  -H "X-Compass-Key: $COMPASS_KEY_RW" -H "Content-Type: application/json" \
  -d '{"sache": "ci-timeout-minuten", "art": "regel",
       "text": "CI-Jobs brechen nach 20 Minuten ab.",
       "herkunft": "entschieden", "angelegt_von": "euer-name",
       "pruefweg_slug": "ci-timeout-grep"}'

Ausführen

curl -sS -X POST "$COMPASS_URL/pruefwege/ci-timeout-grep/run" -H "X-Compass-Key: $COMPASS_KEY_RW"

Läuft mit 30-Sekunden-Timeout, speichert letzter_lauf/letztes_ergebnis, schreibt einen Fakt (herkunft=gemessen, quelle=pruefweg:<slug>) und bestimmt abweichung (passt das Ergebnis zur erwartung?). Ein sauberer Lauf (abweichung=false) löst jeden offenen Abweichungs-Zustand dieses Prüfwegs auf.

In der Oberfläche

Unter Prüfwege (Seitenleiste, Abschnitt „Projekt") stehen alle Prüfwege an einem Ort: was jeder prüft, wann er zuletzt lief, was dabei herauskam und an welchen Regeln er hängt. Ein Knopf „Jetzt ausführen" ruft denselben POST /pruefwege/{slug}/run wie oben.

Darüber steht die Liste der ungeprüften Regeln: geltende Regeln ohne Prüfweg, mit einem beendeten Prüfweg oder mit einem, der noch nie gelaufen ist. Lässt sich das Regelbuch nicht abrufen, sagt die Liste „unbekannt" — nicht „keine".

Was gerade abweicht ansehen

curl -sS "$COMPASS_URL/abweichungen" -H "X-Compass-Key: $COMPASS_KEY_RO"

Jeder Eintrag nennt eine bestimmte Ursache — nie geraten:

  • verstoss — der Prüfweg lief und widersprach der Regel wirklich.
  • werkzeug_fehlt — das Ergebnis trifft ein bekanntes Werkzeug-fehlt-Muster (gh fehlt, kein git-repo, command not found, permission denied, no such file or directory, timeout nach 30s). Dieses Muster gewinnt immer gegen die rohe Erfüllt/Nicht-erfüllt-Lesart — ein fehlendes Werkzeug ist kein Verstoß.
  • unklar — die Erwartung selbst ließ sich nicht als wahr oder falsch gegen das Ergebnis auswerten.

stumm=true ab drei aufeinanderfolgenden werkzeug_fehlt-Läufen desselben Prüfwegs — ein Prüfweg, der immer wieder ein fehlendes Werkzeug meldet, hört auf, als aktiver Alarm zu erscheinen (er bleibt in dieser Liste stehen; nur aus der GET /offen-Zählung fällt er heraus, verschwindet also nie still). Nichts hier löst sich von selbst auf, außer durch einen der drei ausdrücklichen Klicks (verfolgen, regel-ueberholt, pruefweg-kaputt) — siehe die REST-Referenz.

Beenden

Ein Prüfweg, der nicht mehr gebraucht wird, wird beendet — nicht gelöscht.

curl -sS -X POST "$COMPASS_URL/pruefwege/ci-timeout-grep/beenden" \
  -H "X-Compass-Key: $COMPASS_KEY_RW" -H 'Content-Type: application/json' \
  -d '{"grund": "Die Prüfung läuft jetzt in der CI.", "von": "euer-name"}'

grund und von sind Pflicht. Ein Zustand ohne Grund ist nach einem Monat ein Rätsel, und ein Prüfweg, der verschwindet, ohne dass jemand dafür einsteht, ist der stille Weg.

Danach gilt:

  • Der Nachtlauf stößt ihn nicht mehr an.
  • Er erscheint nicht mehr unter GET /abweichungen.
  • Der Rundgang zählt ihn nicht mehr mit — auch nicht im Nenner.
  • POST .../run antwortet 409 und nennt den Grund.

Die Zeile bleibt. GET /pruefwege liefert sie weiter, mit beendet_am, beendet_grund, beendet_von und unverändertem letzten Lauf. Ein zweites Beenden ist 409: der erste Grund ist der, der gilt.