trailofbits/pr-improver

PR Improver

Verbessere den aktuellen Branch durch Ausführen von /code-improver:improve — ein dynamischer Workflow, der einen PR-Reviewer und einen Korrektur-Subagenten in einer Schleife über die Änderungen des Branches ausführt, bis ein Review null kritische/schwerwiegende Befunde meldet. Die Schleife, ihr Verzeichnis und ihre Sicherheitsmechanismen befinden sich im Workflow; dieser Skill leitet den Umfang aus dem Branch-Diff ab und gibt das Ergebnis weiter.

Starten der Schleife

Der Benutzer hat bereitgestellt: $ARGUMENTS (wenn leer, Basis-Branch und Präferenzen aus dem Gespräch übernehmen).

1. Branch und seine Änderungsoberfläche ermitteln

1. Repository-Wurzel: git rev-parse --show-toplevel. Fehlerhaft ausgeben, wenn nicht in einem Repository.
2. Basis: das Argument, falls angegeben, sonst der Standard-Branch des Repositorys (git symbolic-ref refs/remotes/origin/HEAD → dessen Kurzname, fallback auf main). Ausführen verweigern, wenn der aktuelle Branch DER Basis-Branch ist — es gibt keinen Diff zu verbessern.
3. Geänderte Dateien: git diff --name-only <basis>...HEAD. Wenn leer, dies mitteilen und stoppen.
4. Umfang: die Verzeichnisse der geänderten Dateien, verbreitert — Dateiglobs pro Datei sind zu eng (PR-Fixes fügen legitimerweise Tests neben geändertem Code hinzu). Jede geänderte Datei auf ihren Repo-relativen Verzeichnisglob <verz>/** abbilden (** im Repository-Stamm nur, wenn Dateien im Stamm geändert wurden), dann deduplizieren und Globs fallen lassen, die von einem anderen abgedeckt werden.

2. Schleifenskript auflösen

Die Schleife ist der dynamische Workflow workflows/improve.js in diesem Plugin. Über den Pfad starten: scriptPath akzeptiert einen absoluten Pfad und das Workflow-Werkzeug löst mit name eingebaute und Projekt-Workflows auf, sodass ein aus dem Marktplatz installierter Workflow möglicherweise nicht auf code-improver:improve antwortet. In der folgenden Reihenfolge versuchen, der erste Treffer gewinnt — die Home-Verzeichnisse kommen vor ., sodass eine installierte Kopie einen Checkout dieses Marktplatzes übertrifft:

1. Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"
2. Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js" (falls diese Variable stattdessen gesetzt ist)
3. Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

Den Pfad genau wie ausgegeben verwenden. Sein Plugin-Verzeichnis — der Pfad mit /workflows/improve.js entfernt — ist pluginRoot. Wenn alle drei leer zurückkommen, einmal {name: "code-improver:improve"} versuchen; falls auch das nicht verfügbar ist, stoppen und mitteilen, dass die Schleife nicht gefunden werden konnte. Keinen Pfad von Hand zusammenbauen und die Schleife nicht improvisieren.

3. Workflow aufrufen

Mit dem Workflow-Werkzeug ausführen: {scriptPath: "<der Pfad aus Schritt 2>", args: {...}}:

{
  "target": "<Repo-Wurzel>",
  "reviewer": {
    "kind": "skill",
    "name": "pr-review-toolkit:review-pr",
    "notes": "Überprüfe die Änderungen des Arbeitsverzeichnisses gegen <basis> als Pull-Request: Korrektheit, Tests, Fehlerbehandlung und die vom Skill vorgeschriebenen Prüfungsdimensionen."
  },
  "scope": ["<abgeleiteter-verz-glob>/**"],
  "pluginRoot": "<das Plugin-Verzeichnis aus Schritt 2>",
  "maxRounds": 5
}

• reviewer — die Vorgabe oben erfordert das pr-review-toolkit-Plugin. Wenn der Benutzer einen anderen PR-Reviewer (Skill oder Agent) benennt, diesen verwenden, mit entsprechend gesetztem kind.
• maxRounds nur, wenn der Benutzer eine andere Obergrenze angefordert hat.
• pluginRoot ermöglicht dem Lauf, seinen Metriksammler zu finden; den Schlüssel nur weglassen, wenn Schritt 2 zum Workflow-Namen durchgefallen ist — der Workflow sucht dann selbst nach sich.
• finalize-Standardeinstellungen sind für PRs korrekt: kein Versionssprung, es sei denn, der Branch befindet sich in einem Plugin, Erzählungsstreifen und Dokumentationsweitergabe erfolgen.
• decision nur bei Fortsetzung (siehe unten).

Der Basis-Snapshot der Schleife ist der Baum zu Schleifenbeginn — sein Umfangswächter schützt die uncommitteten Arbeiten des Branches; die eigenen Commits des PRs werden vom Reviewer überprüft.

Der Workflow läuft im Hintergrund und benötigt keine Überwachung: er überprüft, korrigiert, überprüft erneut, prüft den Umfang nach jeder Korrekturrunde und kann nur bei einem sauberen Review abgeschlossen werden. Er macht niemals Commits; alle Änderungen bleiben im Arbeitsverzeichnis.

Wenn das Workflow-Werkzeug nicht verfügbar oder verweigert wird, stoppen und dies mitteilen. Die Schleife nicht inline mit direkten Bearbeitungen improvisieren — das Verzeichnis, der Umfangswächter und die Eskalationsgarantien befinden sich im Workflow, und eine Inline-Imitation hat keine davon.

Wenn das Ergebnis halted: "reviewer-unavailable" ist, dies weiterleiten und stoppen. Der Reviewer ist in dieser Sitzung nicht installiert; dem Benutzer mitteilen, welches Plugin ihn bereitstellt (die Vorgabe benötigt pr-review-toolkit), und nach der Installation erneut ausführen. Den Branch nicht selbst überprüfen.

Die eigene Runde nicht beenden, während die Schleife läuft. Das Workflow-Werkzeug gibt sofort eine Aufgaben-ID zurück; das Ergebnis kommt später. In einer interaktiven Sitzung ruft die Fertigstellungsbenachrichtigung einen erneut auf — darauf warten. In einem nicht-interaktiven Lauf (skriptgesteuert, CI, Evaluierung) gibt es keine spätere Runde: Ein Stoppen bricht die Schleife mitten in einer Runde ab. Nach dem Starten daher die Aufgabe abfragen (TaskOutput mit der zurückgegebenen Aufgaben-ID oder sleep-and-recheck), bis sie abgeschlossen ist, dann das Ergebnis weiterleiten. Eine Sitzung, die antwortet "die Schleife läuft, ich melde mich später", hat den Lauf verloren.

Ergebnis weiterleiten

Der Workflow gibt ein strukturiertes Ergebnis zurück. Dies ehrlich melden — die Unterscheidungen sind wichtig:

• converged: true — die letzte Aktion war ein Review mit null kritischen/schwerwiegenden Befunden. Verwendete Runden, verbleibende geringfügige Befunde (open_minor_count) und die Artefaktpfade (ledger_path, metrics) melden.
• capped: true — das Korrekturbudget war erschöpft und das ENDGÜLTIGE Review fand immer noch blockierende Probleme. Klar sagen: abgebrochen, NICHT konvergiert, und open_blocking auflisten. Dies nicht als Erfolg darstellen.
• escalation — die Schleife hat festgestellt, dass sie nicht konvergiert (wiederkehrende Befunde, nicht abnehmende Zählungen oder eine Korrektur, die ein Problem verlagert). Die Eskalationsnachricht und Befund-IDs an den Benutzer weiterleiten: Dies erfordert eine Designentscheidung, nicht weitere Runden.
• halted — ein Wächter hat ausgelöst (Umfangsverletzung, nicht registrierte neue Dateien, ein toter oder nicht verfügbarer Reviewer oder ein Finalize-Durchlauf, dessen eigene Bearbeitungen die darauf folgende Prüfung nicht bestanden haben). Die Pfade in violations/new_untracked_files, die Stellen in finalize_regressions und die Hinweise weiterleiten.
• notes sind immer im Ergebnis enthalten — diese sichtbar machen; sie enthalten laute Warnungen wie "ein Git-Repository wurde initialisiert".

Fortsetzen nach einer Eskalation

Die Schleife stoppt bei Eskalation (designbedingt). Wenn der Benutzer entscheidet, einen neuen Lauf mit denselben Argumenten plus starten:

{ "decision": "<die Entscheidung des Benutzers, wörtlich>" }

Der neue Lauf lädt das auf der Festplatte befindliche Verzeichnis neu, sodass jeder Befund, jede Ablehnung und jedes Urteil übertragen wird — Runden beginnen neu, eine Neuableitung findet nicht statt.

Zum Stoppen einer laufenden Schleife die Workflow-Aufgabe stoppen (TaskStop); das Verzeichnis auf der Festplatte ist auf dem Stand der letzten Runde, und ein erneuter Lauf nimmt von dort wieder auf.

Wann NICHT zu verwenden

• Einmaliges Review: den PR-Review-Skill direkt ausführen; der Wert der Schleife liegt in der Iteration
• Ein Skill: den skill-improver-Eintrag verwenden — dieser verdrahtet den richtigen Reviewer
• Nicht gepushte explorative Arbeit: Überprüfungs- und Korrekturschleifen härten einen Diff; während die Form noch fließend ist, gibt manuelle Iteration mehr Kontrolle