COMPASS-Doku
ENDE

Konzepte

COMPASS speichert eine Form: Eine Sache (eine verfolgte Frage) trägt Aussagen (datierte Behauptungen, die sie beantworten). Alles andere — Regeln, Hypothesen, Lehren, Personas — ist dieselbe Form, angewendet auf eine bestimmte Aufgabe.

Konzept Was es ist
Sache Eine stabile Frage, deren aktuelle Antwort COMPASS verfolgt, z. B. „welches Test-Framework benutzen wir". Kenntlich am kebab-case slug; optional einem bereich und einer stufe zugeordnet.
Aussage Eine datierte Behauptung, die eine Sache beantwortet. Jede Aussage hat eine art (siehe unten), eine herkunft (wie sie entstand: gemessen, gesagt, abgeleitet, entschieden, evidenz) und einen status.
Fakt (art=fakt) Eine gemessene oder beobachtete Aussage — typischerweise von einem Prüfweg nach dessen Lauf geschrieben.
Regel (art=regel) Die Aussage-Art mit Biss: für eine Sache und ein Subjekt darf höchstens eine regel gelten (status=gilt) — von der Datenbank erzwungen, nicht von Anwendungscode.
Entscheidung (art=entscheidung) Ein Klick eines Menschen, mit seiner Quelle festgehalten (eine beantwortete Frage, ein importierter Log-Eintrag, …).
Hypothese (art=hypothese) Eine vorläufige Aussage, die zwingend eine frist (Frist) und einen pruefweg_slug (welcher Prüfweg sie bestätigt oder widerlegt) trägt — der Vertrag weist eine Hypothese ohne beides zurück.
Lehre Ein eigener Datensatz (compass_lehren, die „Hall of Lessons") für Fehler, Gelungenes oder einen Hinweis eines Agenten an einen Menschen. Eine Lehre kann zur Regel werden, aber nur über einen ausdrücklichen menschlichen Klick — nie automatisch.
gilt_seit / gilt_bis Das Gültigkeitsintervall: seit wann eine Aussage gilt und bis wann (null = gilt noch). Die Zeitachse, die die Fachlichkeit interessiert.
beobachtet_am / erfasst_am Das bi-temporale Paar: wann der zugrunde liegende Sachverhalt tatsächlich beobachtet wurde, gegenüber wann COMPASS ihn erfasst hat. Beide können auseinanderfallen — ein Prüfweg kann über etwas berichten, das früher geschah.
Ablösen statt löschen Es gibt kein DELETE auf Aussagen. Eine neue Aussage löst die alte ab (ersetzt zeigt auf die Vorgängerin, die status=abgeloest und gilt_bis = gilt_seit der Nachfolgerin bekommt), oder eine Aussage wird ausdrücklich beendet (POST /aussagen/{id}/beenden), wenn nichts sie ersetzt. Geschichte wird nie gelöscht. Warum, steht in Regel setzen und ablösen.
Genau eine geltende Regel je Sache Ein partieller Unique-Index (uq_aussagen_eine_geltende_regel, auf (kunde_slug, sache, subjekt_id) WHERE art='regel' AND status='gilt') macht eine zweite gleichzeitig geltende Regel für dasselbe Subjekt uneinfügbar — die Datenbank verweigert es, nicht nur die API-Schicht.
warum, Prüfweg, Abweichung GET /warum/{sache} beantwortet „warum gilt diese Regel" mit Entscheidungstext und Historie. Ein Prüfweg ist ein lesender, erlaubte-Befehle-geprüfter Befehl, der eine Regel gegen die Wirklichkeit prüft; ein Lauf, der nicht zur Erwartung der Regel passt, ist eine Abweichung mit bestimmter Ursache (Verstoß, Werkzeug fehlt, oder unklar).
Mandant + Schlüssel Jede Zeile trägt einen kunde_slug (Mandant), von Postgres-Zeilenschutz (Row-Level Security) erzwungen. Ein vorgelegter X-Compass-Key löst genau einen Mandanten und einen Umfang auf: ro (lesen), rw (lesen und schreiben) oder bruecke (nur drei schmale Schreibpfade).
Persona + Brief Eine Persona ist eine Agenten-Identität mit Aufgabe, Grenzen, Stil und einem sichtfeld (Sichtbarkeit — welche Bereiche sie lesen darf). Ihr Brief ist ein deterministisches Markdown-Dokument (kein LLM beteiligt), aus ihren Regeln, ihrem Gedächtnis und ihren Lehren zusammengesetzt, auf ein Zeichen-Budget zugeschnitten.

Wie die Lebenszeit einer Aussage funktioniert

Eine Sache trägt nie selbst Text — sie trägt eine Kette von Aussagen. Eine Regel abzulösen behält die alte Zeile (jetzt abgeloest) und fügt eine neue ein, über ersetzt verknüpft. Das Diagramm zeigt eine Sache mit zwei Regel-Aussagen: die erste wurde abgelöst, als die zweite geschrieben wurde.

Sache welches Test-Framework? AUSSAGE · art=regel "wir nutzen pytest" gilt_seit 2026-01-10 gilt_bis 2026-06-02 AUSSAGE · art=regel "wir nutzen vitest" gilt_seit 2026-06-02 gilt_bis — (status=gilt) ersetzt status: abgeloest status: gilt (die eine geltende Regel)

GET /gilt/{sache} liefert zu jedem Zeitpunkt genau die eine Zeile mit status=gilt — die Abfrage muss nie konkurrierende Antworten abgleichen, weil die Datenbank ohnehin nur eine gleichzeitig erlaubt.

Ledger unabhängig prüfen

Das einzelne Python-Programm core/scripts/ledger_pruefen.py rechnet eine vollständige exportierte Kundenkette offline nach, ohne COMPASS oder zusätzliche Pakete. Mit python3 ledger_pruefen.py kette.json --kopf kopf.json vergleicht ihr sie mit einem separat aufbewahrten Kopf; so fällt auch ein abgeschnittenes Ende auf. Ein Bruch nennt die erste betroffene Nummer. Eine leere Kette oder ein fehlender Kopf liefert keine Erfolgsmeldung. Der Ledger-Export selbst ist noch nicht Teil des Export-Endpunkts; das Eingabeformat ist für dessen spätere Erweiterung festgelegt. Der Prüfer bestätigt den Abgleich mit eurem aufbewahrten Kopf, nicht dessen Herkunft oder die Wahrheit der gespeicherten Aussagen.

Weiter