From cba70b67a1eb7d2b4c1b95a2a91d2da7f29cf6ea Mon Sep 17 00:00:00 2001 From: dschlueter Date: Fri, 29 May 2026 18:08:00 +0200 Subject: [PATCH] docs: neue Flags, Quick-Judge und parallele Server-Checks dokumentiert MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - --no-tests und --approve-concerns in Syntax, Beschreibungen und Beispielen - Quick-Check für Runde 1 im Ablaufbeispiel erklärt - --continue: Hinweis auf parallele Server-Bereitschaftsprüfung - Abschnitt 11 (Anwendungsfälle): neue Beispiele für --no-tests / --approve-concerns - CLAUDE.md: currentModelKey-Cache, normalizeForComparison, quickJudgePrompt dokumentiert Co-Authored-By: Claude Sonnet 4.6 --- BEDIENUNGSANLEITUNG.md | 41 +++++++++++++++++++++++++++++++++++++---- CLAUDE.md | 21 ++++++++++++++------- README.md | 4 ++-- 3 files changed, 53 insertions(+), 13 deletions(-) diff --git a/BEDIENUNGSANLEITUNG.md b/BEDIENUNGSANLEITUNG.md index 20c52ab..9adb373 100644 --- a/BEDIENUNGSANLEITUNG.md +++ b/BEDIENUNGSANLEITUNG.md @@ -279,6 +279,7 @@ Empfohlene Sofortmaßnahmen: keine ``` /optimize [--rounds N] [--with-doku] [--continue] [--interactive] + [--no-tests] [--approve-concerns] [--test-cmd "cmd"] [--test-timeout N] ``` - `--rounds N` — maximale Anzahl Runden (Standard: 2) @@ -286,8 +287,16 @@ Empfohlene Sofortmaßnahmen: keine - `--continue` — überspringt die Implementierungsphase und startet direkt mit dem Judge→Fix-Zyklus ab dem aktuellen Code-Stand. Nützlich wenn man bereits manuell `/coder`, `/judge` und `/fix` durchgeführt hat und den Rest automatisieren möchte. + Im `--continue`-Modus werden Coder- und Judge-Server gleichzeitig geprüft. - `--interactive` — pausiert nach erstem PASS für einen menschlichen Checkpoint. Details: siehe [Interactive-Modus](#interactive-modus) weiter unten. +- `--no-tests` — überspringt die automatische Test-Erkennung. Sinnvoll wenn keine + Test-Suite vorhanden ist oder Tests über externe Infrastruktur laufen. +- `--approve-concerns` — behandelt „PASS WITH CONCERNS" wie „PASS": kein ShipIt-Call, + direktes SHIP. Für Projekte, bei denen du dem Judge-Urteil vertraust. +- `--test-cmd "befehl"` — überschreibt die automatische Test-Erkennung mit einem + eigenen Befehl (z.B. `--test-cmd "pytest tests/ -x"`). +- `--test-timeout N` — maximale Laufzeit pro Test-Befehl in Sekunden (Standard: 120). ### Beispiel: einfacher Auftrag @@ -298,21 +307,25 @@ Empfohlene Sofortmaßnahmen: keine Was im Hintergrund passiert: ``` Phase 1: Coder implementiert... -Phase 2: Runde 1/2: Judge prüft... +Phase 2: Runde 1/2: Quick-Check (kompakter Erstcheck)... → Urteil: FAIL (2 Blocker) Phase 3: Runde 1/2: Coder fixt... -Phase 4: Runde 2/2: Judge prüft... +Phase 4: Runde 2/2: Judge — TASK.md + letzter Commit + Tests... → Urteil: PASS WITH CONCERNS ✓ PASS WITH CONCERNS nach Runde 2 -Finale ShipIt-Prüfung... (nur bei PASS WITH CONCERNS) +Finale ShipIt-Prüfung... (nur bei PASS WITH CONCERNS, nicht bei klarem PASS) → SHIP [Dialog: Version → v0.1.0 (empfohlen)] ``` +**Runde 1 = Quick-Check:** Kompakter Prompt ohne TASK.md-Analyse — erkennt offensichtliche +Fehler schnell. Erst ab Runde 2 (oder bei `--continue`) kommt der vollständige Judge-Prompt. + Bei klarem `PASS` entfällt die ShipIt-Runde — es wird direkt SHIP ausgelöst. +Mit `--approve-concerns` gilt das auch für `PASS WITH CONCERNS`. Während des Ablaufs zeigt die Statuszeile immer die aktuelle Aktivität: -`Coder implementiert…` → `Editiere src/main.rs…` → `Git-Commit…` → `Judge reviewt (Runde 1/2)…` +`Coder implementiert…` → `Quick-Check…` → `Coder fixt Blocker…` → `Judge reviewt (Runde 2/2)…` ### Beispiel: mehr Runden @@ -694,6 +707,26 @@ Die Checkboxen werden automatisch abgehakt: /quick_check ``` +### Repo ohne Test-Suite oder mit externer CI + +```bash +# Test-Erkennung überspringen — Judge bewertet nur den Code +/optimize "Implementiere Feature X" --no-tests + +# Externe Test-Suite explizit angeben +/optimize "Implementiere Feature X" --test-cmd "make integration-test" +``` + +### Schneller Loop ohne ShipIt-Runde + +```bash +# Für Projekte wo "PASS WITH CONCERNS" ausreicht: +/optimize "Kleines Refactoring" --approve-concerns + +# Kombination: kein Test, kein ShipIt bei Concerns, 1 Runde +/optimize "Typo-Fix in Fehlermeldungen" --rounds 1 --no-tests --approve-concerns +``` + ### Versionsnummer nach der Entwicklung setzen ```bash diff --git a/CLAUDE.md b/CLAUDE.md index d685c82..cde1fd7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -40,13 +40,17 @@ Beide nutzen dasselbe GGUF (`Qwen3.6-27B-Uncensored-HauhauCS-Aggressive-IQ4_XS.g **Zentraler Ablauf in `/optimize`:** 1. `writeTaskMd()` → TASK.md anlegen -2. Coder: `coderKickoff()` → implementiert + committet -3. Äußere `while(keepGoing)`-Schleife (für `--interactive`-Zusatzaufträge) -4. Loop (max. N Runden, Standard 2): Judge → `parseVerdict()` → PASS? → break. FAIL? → `parseBlockers()` → Fix → nächste Runde -5. Bei PASS + `--interactive`: Polling auf `interactiveContinueRequested`. Kein Zusatzauftrag → ShipIt. Zusatzauftrag → `coderKickoff()` → `keepGoing = true` -6. SHIP-Schritt: klares `PASS` → direkt SHIP (kein ShipIt-Call). `PASS WITH CONCERNS` → `shipitPrompt()` → SHIP/NO-SHIP -7. Loop-Erkennung: gleicher Blocker zweimal → Abbruch (`finalNotify()`) -8. Optional: `runUpdateDoku()` bei `--with-doku` +2. `--continue`-Modus: Coder- und Judge-Server **parallel** via `Promise.all(waitUntilModelReady×2)` prüfen +3. Coder: `coderKickoff()` → implementiert + committet +4. Äußere `while(keepGoing)`-Schleife (für `--interactive`-Zusatzaufträge) +5. Loop (max. N Runden, Standard 2): + - Runde 1 (ohne `--continue`): `quickJudgePrompt()` / `quickJudgeWithTestsPrompt()` — kurzer Erstcheck + - Runde 2+: `judgePrompt()` / `judgeWithTestsPrompt()` — vollständige Analyse mit TASK.md + - `parseVerdict()` → PASS? → break. FAIL? → `parseBlockers()` → `normalizeForComparison()` → Loop-Check → Fix → nächste Runde +6. Bei PASS + `--interactive`: Polling auf `interactiveContinueRequested`. Zusatzauftrag → `coderKickoff()` → `keepGoing = true` +7. SHIP-Schritt: `PASS` oder (`PASS WITH CONCERNS` + `--approve-concerns`) → direkt SHIP. `PASS WITH CONCERNS` sonst → `shipitPrompt()` → SHIP/NO-SHIP +8. Loop-Erkennung: `normalizeForComparison(currentBlockers) === normalizeForComparison(lastBlockers)` → Abbruch +9. Optional: `runUpdateDoku()` bei `--with-doku` **`tool_call`-Hook (edit-Reordering):** Sortiert Multi-Edit-Aufrufe auf dieselbe Datei von hinten nach vorne. Verhindert den Fehler „edits[n] doesn't match" wenn mehrere Stellen einer Datei auf einmal geändert werden. @@ -63,6 +67,9 @@ Kritische Felder bei llama-cpp-Providern: `contextWindow` muss mit dem `-c`-Para ## Wichtige Invarianten - **`cancelRequested`** ist eine modulare Variable — sie wird von `/cancel` gesetzt und nach jedem Loop-Schritt in `/optimize` geprüft und zurückgesetzt. +- **`currentModelKey`** — Cache für `switchModel()`: speichert `"provider/modelId"` des zuletzt gesetzten Modells. Bei identischem Key wird `pi.setModel()` übersprungen. Wird im `finally`-Block auf `""` resettet. +- **`normalizeForComparison(s)`** — Hilfsfunktion für die Loop-Erkennung: normalisiert Whitespace und Satzzeichen vor dem String-Vergleich, verhindert False-Negatives. +- **`quickJudgePrompt()` / `quickJudgeWithTestsPrompt()`** — kompakte Prompt-Varianten für Runde 1 (ohne `--continue`): kein TASK.md, nur Diff + Testergebnis. Bei FAIL folgt Runde 2 mit `judgePrompt()`. - **`interactivePauseActive` / `interactiveContinueRequested` / `interactivePauseTask`** — drei modulare Variablen für den `--interactive`-Modus. `interactivePauseActive` wird vom `/continue`-Command geprüft, um zwischen Interactive-Pause-Signal und normalem Fortsetzen zu unterscheiden. Alle drei werden im `finally`-Block zurückgesetzt. - **`sendAndWait()`** wartet erst auf `idle`, dann `deliverAs: "followUp"` — verhindert „Agent is already processing". - **`tickTaskMdStatus()`** nutzt Python3 für den String-Ersatz in TASK.md (kein Shell-Escaping-Problem). diff --git a/README.md b/README.md index 5f5aed4..17e3c52 100644 --- a/README.md +++ b/README.md @@ -285,8 +285,8 @@ wenn pi agent Folgeanfragen schnell hintereinander schickt. | `/judge [fokus]` | Judge | Code-Review gegen TASK.md + letzten Commit | | `/fix [hinweis]` | Coder | Judge-Kritik beheben, committen | | `/shipit` | Judge | Finale Freigabeprüfung | -| `/optimize [--rounds N] [--with-doku] [--continue] [--interactive]` | beide | Vollautomatische Schleife bis PASS (Standard: 2 Runden) | -| `/optimize ... [--test-cmd "cmd"] [--test-timeout N]` | beide | Externe Test-Suite im Loop ausführen | +| `/optimize [--rounds N] [--with-doku] [--continue] [--interactive]` | beide | Vollautomatische Schleife bis PASS (Standard: 2 Runden, Runde 1: Quick-Judge) | +| `/optimize ... [--no-tests] [--approve-concerns] [--test-cmd "cmd"] [--test-timeout N]` | beide | Test-Erkennung überspringen / PASS WITH CONCERNS direkt shippern | | `/patch <änderung>` | Coder | Gezielte Minimaländerung ohne Review | | `/quick_check [was]` | Judge | Schnelle Prüfung der letzten Änderung | | `/version` | — | Versionsnummer erhöhen (SemVer + Git-Tag) |