koffih/proof-of-done

Beweis der Erledigung (Proof of done)

Du entscheidest nicht, dass eine Arbeit erledigt ist. Ein Skript tut dies anhand von Quittungen. Deine Aufgabe ist es, den Vertrag zu schreiben, die Beweise zu erbringen und das Urteil, das das Skript berechnet, Wort für Wort zu melden.

Anfrage: $ARGUMENTS

Die Regel

OHNE QUITTUNG KEINE BEHAUPTUNG.
Eine Quittung zählt nur für den Code, auf dem sie erstellt wurde.
Das Urteil wird berechnet, niemals von Hand geschrieben.

„Fertig“, „repariert“, „funktioniert“, „bestanden“, „bereit“, „bereitgestellt“, „alles gut“, ein Häkchen oder jeder Satz, der den Leser glauben lässt, dass einer dieser Zustände vorliegt, ist eine Behauptung. Das Gleiche gilt für „sollte funktionieren“, was eine Behauptung mit einer Ausrede ist. Jede Behauptung benötigt eine PROVEN-Zeile im Hauptbuch für den aktuellen Baum, sonst wird sie nicht aufgestellt.

Die Engine

scripts/proof.py im Ordner dieser Fähigkeit (normalerweise ~/.claude/skills/proof-of-done/scripts/proof.py oder .claude/skills/proof-of-done/... in einem Projekt). Standardbibliothek, Python 3.8+. Einmal pro Sitzung einrichten:

P="python3 $(ls -d ~/.claude/skills/proof-of-done .claude/skills/proof-of-done 2>/dev/null | head -1)/scripts/proof.py"

Alles lebt in .proof/ im Projektstammverzeichnis: acceptance.md (der Vertrag, committen), contract.lock und contract-log.md (committen), receipts.jsonl und artifacts/ (lokale Beweise, git-ignoriert).

Die fünf Schritte

1. Vertrag, vor dem Code

$P init, dann schreibe .proof/acceptance.md. Eine Zeile pro Kriterium, vier Felder:

- AC1 :: ein eingeloggter Benutzer kann Gmail verbinden und sieht "Verbunden" :: e2e :: run: npx playwright test tests/gmail-connect.spec.ts
- AC2 :: eine E-Mail wird zu einer Aufgabe mit ihrem Betreff als Titel :: integration :: run: pytest tests/test_email_to_task.py -q
- AC3 :: die Inbox-Seite zeigt die neue Aufgabe ohne Neuladen :: visual :: see: screenshot nach dem Konvertieren einer E-Mail

• Ein Kriterium beschreibt, was jemand beobachten kann (ein Benutzer, ein Aufrufer, eine Datei, eine Zeile), nicht welcher Code existiert. „Einen Handler hinzugefügt“ ist kein Kriterium.
• Die Stufe ist die Stärke des Beweises, den die Behauptung benötigt. Lese references/proof-ladder.md, um sie auszuwählen: Eine UI-Behauptung benötigt mindestens e2e oder visual, ein Bugfix benötigt einen Test, der vor dem Fix fehlgeschlagen ist, ein Deployment benötigt runtime auf dem deployed Ziel.
• run: ist der genaue Befehl, der nur mit Exit 0 beendet wird, wenn das Kriterium erfüllt ist. Schreibe ihn so, wie du ihn ausführen wirst. Eng gefasst ist in Ordnung (eine Testdatei), nichtssagend ist es nicht (true, echo ok, ein Test ohne Behauptung).
• Wenn der Benutzer Kriterien genannt hat, verwende seine Worte. Wenn nicht, leite sie aus der Anfrage ab, zeige sie in einem kurzen Block und fahre fort (warte nicht, es sei denn, ein Kriterium ist wirklich mehrdeutig). Füge eine Liste ## Außerhalb des Umfangs hinzu, damit niemand dich für das bewertet, was nicht gefragt wurde.
• $P freeze. Von nun an zeigt sich das Entfernen eines Kriteriums, das Herabsetzen einer Stufe oder das Austauschen eines Befehls gegen einen einfacheren in contract-log.md und benötigt --reason mit Zustimmung des Benutzers. Das Hinzufügen von Kriterien ist immer in Ordnung.

Bei einer einzeiligen Änderung kann der Vertrag aus einem einzigen Kriterium bestehen. Er existiert trotzdem.

2. Bauen, Beweisen während des Vorgehens

Implementiere normal. Nach jedem kohärenten Schritt führe $P run AC2 (oder $P run --all) aus und lies, was es ausgibt. Eine FAILED-Zeile ist Information, kein Hindernis, das man umgehen sollte: Lies die Ausgabe, behebe die Ursache, führe erneut aus. Führe bei einem Bugfix den neuen Test vor dem Fix aus und behalte diese fehlschlagende Quittung im Hinterkopf: Ein Regressionstest, der nie fehlgeschlagen ist, beweist nichts (rot, dann grün).

Für see:-Kriterien: Erstelle den Beweis (Playwright-Screenshot, curl -i-Ausgabe in einer Datei gespeichert, exportierte CSV, Log-Auszug), öffne ihn und schaue ihn dir an (Lies das Bild, lies die Datei), dann $P attach AC3 path/to/shot.png --note "Inbox nach Konvertierung, Aufgabe sichtbar". Die Datei wird in .proof/artifacts/ kopiert, um andere Quittungen nicht zu stören. Einen Screenshot anzuhängen, den du dir nicht angesehen hast, ist dieselbe Lüge, wie einen Test zu zitieren, den du nicht ausgeführt hast.

3. Urteil

$P run --all      # frische Quittungen für jedes run:-Kriterium, auf dem finalen Baum
$P verdict        # das Hauptbuch und das Urteil; Exit 0 nur bei DONE

Zustände: PROVEN (Quittung besteht auf dem aktuellen Baum), FAILED, PENDING (keine Quittung), STALE (Code nach dem Beweis geändert), MISMATCH (die Quittung hat einen anderen Befehl als den Vertrag ausgeführt), SUSPECT (Exit 0, aber null Tests liefen, nur Überspringungen, fehlendes Tool oder der Beweis hat den Baum bearbeitet), BLOCKED, WAIVED. Urteile: DONE, DONE WITH WAIVERS, BLOCKED, NOT DONE.

Jede Bearbeitung nach dem letzten Lauf, selbst ein Kommentar, macht Quittungen STALE. Das ist der Punkt: Führe zuletzt aus, melde direkt danach.

4. Unabhängige Prüfung

Der Ersteller bewertet seine eigene Arbeit nie. Wenn die Aufgabe mehr als eine kleine Änderung ist, eine UI, ein Deployment oder Daten betrifft oder von Sub-Agenten erledigt wurde, starte einen Prüf-Subagenten mit der Eingabeaufforderung in references/checker.md. Dieser liest den Vertrag erneut, führt die Beweise selbst erneut aus, sieht sich die angehängten Dateien an, liest den Diff auf Umfangserweiterungen und Gate-Manipulationen und gibt ACCEPT oder REJECT mit Begründung zurück. Ein REJECT geht zurück zu Schritt 2. Wenn dir ein Sub-Agent mitteilt, dass er erfolgreich war, behandle es genauso: git diff --stat, führe seinen Beweis selbst aus.

5. Bericht

Beginne mit der Urteilszeile genau wie berechnet, dann die Quittungen:

URTEIL: DONE   (oder NOT DONE / BLOCKED / DONE WITH WAIVERS)

| Kriterium | Beweis | Ergebnis |
|---|---|---|
| AC1 Benutzer verbindet Gmail, sieht "Verbunden" | npx playwright test tests/gmail-connect.spec.ts | exit 0, 3 bestanden |
| AC2 E-Mail wird Aufgabe | pytest tests/test_email_to_task.py -q | exit 0, 5 bestanden |
| AC3 Inbox zeigt Aufgabe ohne Neuladen | .proof/artifacts/AC3-...png (angesehen) | Aufgabe oben sichtbar |

Prüfer: ACCEPT (oder REJECT: ...)
Nicht bewiesen: keine   (oder jedes offene Kriterium, warum, und der nächste Schritt)
Außerhalb des Umfangs: ...

Bei NOT DONE sage dies zuerst und klar, dann was bewiesen ist, was nicht, und den kleinsten nächsten Schritt. Ein klares NOT DONE ist ein guter Bericht. Ein DONE, das sich als falsch herausstellt, kostet den Benutzer eine Debugging-Sitzung und ihr Vertrauen.

Sprachwächter

Bevor du eine Nachricht sendest, überprüfe sie. Diese benötigen eine PROVEN-Quittung auf dem aktuellen Baum, sonst werden sie entfernt:

• done, finished, complete, fixed, resolved, works, working, passes, green, ready, shipped, deployed, live, all good, should work, should be fixed, probably, looks good, ✅, "Perfect!", "Great, that worked"
• „Tests bestanden“, wenn du eine Teilmenge ausgeführt hast; „Build bestanden“, wenn du den Linter ausgeführt hast; „bereitgestellt“, wenn du gepusht hast; „repariert“, wenn du Code geändert und das Symptom nicht reproduziert hast.

Sage, was du ausgeführt hast und was es zurückgegeben hat: „pytest tests/test_email_to_task.py: 5 bestanden, exit 0“ trägt sich selbst. Wenn du es nicht ausgeführt hast: „noch nicht verifiziert“.

Die vollständige Tabelle der Ausreden und die Arten, wie ein Beweis umgangen werden kann, finden sich in references/anti-gaming.md. Lies es einmal pro Projekt; die Kurzfassung: Schwäche niemals, überspringe, mokiere oder lösche niemals die Sache, die die Behauptung beweist, und bearbeite niemals einen Test, um einer falschen Ausgabe zu entsprechen.

Stop-Hook (optional, pro Projekt)

$P hook --install fügt einen Stop-Hook zu ./.claude/settings.local.json hinzu (--shared für das committete settings.json). Wenn in einem Projekt mit .proof/acceptance.md die Sitzung zu enden versucht, während das Urteil nicht DONE ist, sendet der Hook sie einmal mit den offenen Kriterien zurück, es sei denn, die letzte Nachricht enthält bereits URTEIL: NOT DONE oder URTEIL: BLOCKED. Es wiederholt sich nie (es lässt den zweiten Stopp durch) und tut nichts in Projekten ohne Vertrag. Installiere es für lange oder unbeaufsichtigte Arbeiten; teile dem Benutzer mit, dass es vorhanden ist.

Wenn der Beweis nicht ausgeführt werden kann

Kein Browser, kein Staging-Zugang, ein fehlendes Geheimnis, eine kostenpflichtige API: Ersetze einen schwächeren Beweis nicht stillschweigend. $P block AC4 --reason "keine Staging-Zugangsdaten" und melde BLOCKED mit der genauen fehlenden Sache und dem Befehl, der sie beweisen würde, sobald sie vorhanden ist. $P waive existiert nur für ein Kriterium, das der Benutzer explizit fallen lässt, in seinen eigenen Worten, zitiert in der Begründung.

Kleine Aufgaben

Ein Tippfehler oder eine einzeilige Konfiguration: ein Kriterium, ein Befehl, eine Quittung, eine Zeile im Bericht (URTEIL: DONE + der Befehl und sein Ergebnis). Die Zeremonie skaliert nach unten; die Regel nicht.