Referenz zu bmad-plus review: Review-Umfang versiegeln, Befunde im Code verankern, aus der Abdeckung ein Urteil ableiten, fortsetzen, vergleichen und Regeln auflisten, mit Optionen und Exit-Codes.
bmad-plus review ist die Nachweisschicht eines Code-Reviews. Es liest deinen Code nicht mit einem Modell und beurteilt ihn nicht: Das Lesen übernimmt der Assistent (meist Sentinel). Der Befehl legt fest, was geprüft wird (der Umfang), kontrolliert, dass jeder zitierte Befund wirklich im Code steht, und leitet das Urteil aus der tatsächlichen Abdeckung ab; ein auf halbem Weg abgebrochenes Review kann so nie als sauber gelten. Nutze es, wenn du ein Review willst, dessen Ergebnis sich prüfen, skripten oder als Bedingung für einen Pull Request verwenden lässt.
Hinweis· Was clean bedeutet
clean heißt: kein offener Befund innerhalb eines vollständig abgedeckten Umfangs. Es beweist nicht, dass der Code korrekt ist, und ein Review ohne Befunde ist erlaubt. Fehlende, gescheiterte oder ungültige Nachweise ergeben incomplete, nie clean.
id benennt ein Review und wird zu einem Ordner: Kleinbuchstaben, Ziffern, Punkte und Bindestriche, beginnend mit Buchstabe oder Ziffer, höchstens 81 Zeichen (zum Beispiel pr-42). rules ist die einzige Aktion, die einen Pfad statt einer ID nimmt.
Die sechs Aktionen
Aktion
Was sie tut
Schreibt
scope <id>
Legt fest, was geprüft wird: die geänderten Dateien zwischen zwei Commits (oder der Arbeitsbaum), welche davon ausgewählt sind, welche Regeln für jede gelten und den Review-Plan.
scope.json, checklist.md
anchor <id>
Validiert findings.json und lokalisiert jedes zitierte Fragment im Code am Head. Zugangsdaten-ähnliche Werte werden im geschriebenen Protokoll durch [REDACTED] ersetzt.
findings.anchored.json
gate <id>
Leitet das Urteil aus Umfang, Abdeckung und verankerten Befunden ab: clean, findings oder incomplete.
optional eine Prüfdatei für CI
continue <id>
Listet auf, was ein unterbrochenes Review noch schuldet, gegen denselben versiegelten Umfang. Abgelehnt, wenn sich Code oder Regeln bewegt haben.
continue.json
compare <id> --since <earlier-id>
Ordnet die Befunde dieses Reviews gegen ein früheres ein: neu, bestehend, gelöst, widerlegt, nicht geprüft.
compare.json
rules [path]
Gibt den wirksamen Regelsatz aus, oder die Regeln, die ein bestimmter Pfad bekäme.
nichts
Optionen von review
Option
Argument
Standard
Was sie tut
-d, --directory
<path>
aktueller Ordner
Projektordner.
--dir
<path>
_bmad-output/review
Review-Ordner im Projekt. Jedes Review liegt in <dir>/<id>/.
--base
<ref>
HEAD~1 (HEAD mit --workspace)
Basis-Commit oder -Branch. Der Umfang beginnt an der Merge-Base von Basis und Head.
--head
<ref>
HEAD
Head-Commit oder -Branch.
--workspace
-
aus
Den Arbeitsbaum gegen die Basis prüfen, nicht verfolgte Dateien eingeschlossen.
--include
<glob>
keine
Nur passende Pfade prüfen. Wiederholbar.
--exclude
<glob>
keine
Passende Pfade nie prüfen. Wiederholbar.
--effort
low|medium|high
medium
Tiefe des Reviews (siehe unten).
--since
<id>
keine
Nur compare: das frühere Review, gegen das verglichen wird. Dort Pflicht.
--emit-check
<file>
keine
Nur gate: schreibt das Urteil zusätzlich als JSON-Prüfergebnis für CI. Muss eine .json-Datei sein.
review scope <id> schreibt scope.json und eine Checkliste der Regeln, die für die geänderten Pfade gelten. Der Umfang hat einen Fingerabdruck: Jede spätere Änderung an Code oder Regeln ist erkennbar.
Im Terminal deines Projekts
npx bmad-plus review scope pr-42 --base main --effort high
02
Prüfen und die Nachweise schreiben
Der Assistent liest die Dateien und schreibt findings.json (jeder Befund zitiert seinen Code wörtlich, mit Kategorie, Schweregrad, Konfidenz und Disposition) sowie coverage.json (jede ausgewählte Datei endet als completed, failed oder waived mit Begründung). BMAD+ ruft dafür nie ein Modell auf.
03
Die Befunde verankern
review anchor <id> findet jedes zitierte Fragment im Code. Von einem Modell geschriebene Zeilennummern werden nie benutzt; nur das Zitat zählt.
Im Terminal deines Projekts
npx bmad-plus review anchor pr-42
04
Das Urteil abfragen
review gate <id> leitet clean, findings oder incomplete ab. Mit --emit-check erhältst du ein JSON-Dokument, das ein CI-Schritt auswerten kann.
Der Befehl liest die Git-Historie und die Dateien des Projekts (er startet git für rev-parse, diff, merge-base und ls-files) sowie die Review-Regeln. Er schreibt nur in <dir>/<id>/, dazu die --emit-check-Datei. Er öffnet keine Netzverbindung und ruft kein Modell auf.
Dateien im Review-Ordner
Datei
Geschrieben von
Inhalt
scope.json
scope
Basis, Head, Merge-Base, ausgewählte und ausgeschlossene Dateien mit Gründen, Regeln je Datei, Einheiten, Plan, Fingerabdruck.
checklist.md
scope
Die Regeln, die für die geänderten Pfade gelten, als Checkliste für die prüfende Person.
Ein unbekannter Wert ist ein Fehler und wird nie stillschweigend korrigiert. Ein widerlegter Befund behält seine Widerlegung, ein bestätigter braucht einen Beleg, eine gescheiterte oder zurückgestellte Datei braucht eine Begründung. Nur run.stop: completed lässt das Gate ein Urteil erreichen; jeder andere Grund hält es auf incomplete. Eine Einheit, die dreimal hintereinander scheitert, wird aufgegeben und bleibt gescheitert.
Ein Durchgang ist ein vollständiges Lesen des Umfangs; spätere Durchgänge suchen, was frühere übersehen haben. Der von scope ausgegebene Plan hängt auch von der Größe ab: ab 150 geänderten Zeilen plant die prüfende Person vor dem Lesen, und bei mehr als einer Einheit und mindestens 400 geänderten Zeilen können die Einheiten parallel geprüft werden. Eine Einheit fasst höchstens 8 Dateien und 400 Zeilen zusammen.
secret: .env*, Schlüssel und Zertifikate (*.pem, *.key, *.p12, *.pfx, id_rsa*, id_ed25519*), .npmrc, .netrc und alles unter credentials/, .credentials/ oder secrets/. Wird vor jedem --include geprüft, kein Muster kann sie hereinholen.
Eine Regel ist eine Markdown-Checkliste, die nach Dateipfad gewählt wird. Jede Regel, deren Muster passt, gilt für die Datei; Regeln addieren sich. Acht werden mit der CLI ausgeliefert.
Eingebaute Regeln
Regel-ID
Gruppe
Gilt für
general
code
jede Datei
javascript-typescript
code
js cjs mjs jsx ts cts mts tsx vue svelte
python
code
py pyi
sql-and-migrations
data
*.sql, Migrationsordner, *.prisma, schema.rb
shell
code
sh bash zsh ps1 psm1, Makefile
ci-workflows
delivery
GitHub Actions, GitLab CI, Bitbucket- und Azure-Pipelines
containers
delivery
Dockerfile, Containerfile, Compose-Dateien, Kubernetes- und Helm-Manifeste
Ist das Shield-Pack installiert, kommen sechs Compliance-Regeln hinzu (sie ersetzen oder deaktivieren nie eine eingebaute): shield-access-control, shield-personal-data, shield-cryptography, shield-logging, shield-ai-integrations und shield-change-and-supply-chain. Jede nennt die Kontrollen, die sie prüft, als FRAMEWORK:ID, etwa ISO27001:A.8.5, SOC2:CC6.1, NIST-800-53:AC-3 oder NIS2:Art.21(2)(i); ein Befund darf nur Kontrollen nennen, die die Regeln seiner Datei prüfen.
Ein Projekt fügt in _bmad/review-rules.yaml Regeln hinzu, ersetzt sie (gleiche ID) oder deaktiviert sie. Die doc-Dateien sind Markdown und werden neben dieser Datei aufgelöst. Eine unbekannte ID zu deaktivieren ist ein Fehler.
findings.json ist ungültig, oder mindestens ein Befund ist mehrdeutig oder nicht lokalisiert: Zitiere ein längeres, exaktes Fragment.
gate
0
clean.
gate
1
findings: Mindestens ein bestätigter oder ungelöster Befund ist offen.
gate
2
incomplete: Eine Datei ist nicht erfasst oder gescheitert, die Nachweise sind ungültig oder fehlen, der Lauf endete vorzeitig, oder ein offener Befund ist nicht verankert.
continue
0
Ein Bündel verbleibender Arbeit wurde geschrieben.
continue
3
moved: Code oder Regeln haben sich seit dem Versiegeln des Umfangs geändert (oder coverage.json ist ungültig).
jede Aktion
3
Fehler: unbekannte Aktion, ungültige ID, fehlender Umfang oder fehlende Befunde, Git-Fehler, unlesbares oder ungültiges JSON.
Diese Mitschnitte sind simuliert: Die Zeilen folgen den Meldungsvorlagen des Befehls, Zahlen und Fingerabdruck sind beispielhaft. Die vom echten Befehl ausgegebenen Pfade sind absolut.
Einen Umfang versiegelnSimuliert
$ npx bmad-plus review scope pr-42 --base main --effort high<project>/_bmad-output/review/pr-42/scope.json3 file(s) to review, 41 changed lines, 1 unit(s) — scope 3f9a1c0d52b7 excluded 1 × generated-or-vendoredchecklist: <project>/_bmad-output/review/pr-42/checklist.mdplan: high effort, 3 pass(es), refutation passEvery selected file must end in coverage.json as completed, failed or waived (with a reason).
npx bmad-plus review scope pr-42 --base main --effort high
Beispielhafter Ablauf, nicht bei einem echten Lauf aufgezeichnet. Quelle: tools/cli/commands/review.js (Meldungsvorlagen der Aktion scope)
Ein Gate, das noch nicht bereit istSimuliert
$ npx bmad-plus review gate pr-42pr-42: incomplete — coverage 1/3 completed (0 waived), 0 open finding(s), 0 refuted - 2 selected file(s) never accounted for: src/a.js, src/b.js# Exit-Code 2. Das Review schuldet noch zwei Dateien.
npx bmad-plus review gate pr-42
Beispielhafter Ablauf, nicht bei einem echten Lauf aufgezeichnet. Quelle: tools/cli/commands/review.js (Aktion gate) und tools/cli/lib/review.js (Begründungen von reviewGate)
Ein sauberes UrteilSimuliert
$ npx bmad-plus review gate pr-42 --emit-check ci/review-check.jsonpr-42: clean — coverage 3/3 completed (0 waived), 0 open finding(s), 0 refuted check: <project>/ci/review-check.json clean: no open finding within a fully covered scope. It does not prove the code correct.# Exit-Code 0.
Beispielhafter Ablauf, nicht bei einem echten Lauf aufgezeichnet. Quelle: tools/cli/commands/review.js (Aktion gate)
Das --emit-check-Dokument ist stabil (ohne Zeitstempel, gleiche Nachweise ergeben gleiche Bytes). Es enthält Status, Exit-Code, Gründe, Zahlen, den Umfang, auf den es antwortet, die offenen Befunde mit ihren Zeilen und einen github-Block in der Form der Check-Runs-API: conclusion (success oder failure) und ein output mit Markdown-Zusammenfassung und bis zu 50 Annotationen. Ein Review des Arbeitsbaums schreibt seine Prüfdatei in den Review-Ordner oder außerhalb des Projekts, damit sie nicht in die Änderung gerät, über die sie berichtet.
Fehler geben review: <message> auf dem Fehlerstrom aus (oder mit --json ein JSON-Objekt mit status: "error") und enden mit 3.
Meldungen
Meldung
Ursache
Was tun
unknown action "x" (scope, anchor, gate, continue, compare, rules)
Die Aktion gehört nicht zu den sechs.
Eine der aufgeführten Aktionen verwenden.
a review id is required: lowercase letters, digits, dots and dashes
Keine ID oder eine ID mit anderen Zeichen.
Eine ID wie pr-42 angeben.
no scope at <path> — run "bmad-plus review scope <id>" first
Im Review-Ordner fehlt scope.json.
review scope <id> mit demselben --dir ausführen.
invalid ref "..." oder git rev-parse failed: ...
Ein --base oder --head, der keinen Commit ergibt.
Referenz prüfen (in CI abrufen); Referenzen mit führendem - werden abgelehnt.
git is unavailable: ...
git liegt nicht im Pfad des Prozesses.
git installieren oder den Pfad korrigieren.
effort must be one of low|medium|high
Unbekanntes --effort.
low, medium oder high verwenden.
no findings at <path>
anchor oder compare fand keine findings.json.
Sie schreiben, auch mit leerer Liste.
--since <earlier review id> is required: ... / --since must name a different review
compare ohne --since oder gegen sich selbst.
Die ID des früheren Reviews angeben.
--emit-check writes a .json file / --emit-check must not overwrite the review evidence
Der Pfad ist keine .json-Datei oder eine der Nachweisdateien.
Einen anderen .json-Pfad wählen.
<id> cannot continue: the sealed scope no longer describes the code.
Exit 3 von continue: Head bewegt, Dateien oder Regeln geändert.
Neuen Umfang mit denselben Optionen versiegeln, dann review compare <new-id> --since <id>.
Gate-Gründe: no coverage.json: ..., no findings.json: ..., N selected file(s) never accounted for: ..., the review stopped before the end (budget): ...
Nachweise fehlen, sind unvollständig, oder der Lauf endete vorzeitig. Exit 2.
Das Review beenden (continue), beide Dateien schreiben, run.stop nur dann auf completed setzen, wenn es stimmt.
Einen Pull Request mit prüfbaren Nachweisen reviewen#
Du möchtest, dass Sentinel die Änderungen des Branches gegenüber main prüft und ein verlässliches Urteil liefert.
In deinem KI-Assistenten
Sentinel, prüfe diesen Branch gegen main. Wenn die BMAD+-CLI verfügbar ist, versiegle den Umfang mit bmad-plus review scope pr-42 --base main --effort high, zitiere jeden Befund wörtlich, verankere und prüfe ihn dann am Gate und berichte die Gate-Antwort, ohne sie aufzuwerten.
Das solltest du erhalten Sentinel führt review scope aus, das scope.json und checklist.md unter _bmad-output/review/pr-42/ schreibt. Er prüft die ausgewählten Dateien, schreibt findings.json und coverage.json, führt review anchor (Exit 1, wenn ein Zitat nicht auffindbar ist) und review gate aus. Er meldet clean, findings oder incomplete genau so, wie das Gate es ausgegeben hat. Ein abgebrochenes oder teilweises Review gilt als unvollständig, nie als sauber.
Die Sitzung endete, bevor alle Dateien gelesen waren, und coverage.json vermerkt run.stop als interrupted.
In deinem KI-Assistenten
Sentinel, setze das Review pr-42 dort fort, wo es endete. Nutze bmad-plus review continue pr-42 und tue nur, was es auflistet.
Das solltest du erhaltenreview continue schreibt continue.json und gibt die noch zu prüfenden Dateien und Einheiten aus, die erneut zu zitierenden Befunde, die verbleibenden Durchgänge und jede nach drei gescheiterten Versuchen aufgegebene Einheit. Haben sich Code oder Regeln bewegt, lehnt es mit Exit 3 ab und verweist auf einen neuen Umfang und review compare. Bleibt nichts übrig, rät es zu review gate, sobald coverage.json den Lauf als abgeschlossen vermerkt.
Der Autor hat Korrekturen gepusht. Du hast einen neuen Umfang pr-43 versiegelt und das zweite Review beendet.
In deinem KI-Assistenten
Sentinel, vergleiche das Review pr-43 mit pr-42 mit bmad-plus review compare pr-43 --since pr-42 und sag mir, was neu ist, was bleibt und was wirklich gelöst ist.
Das solltest du erhalten Der Befehl gibt pr-43 since pr-42: N new, N persisting, N resolved, N refuted, N not reviewed aus und schreibt compare.json. Ein Befund des früheren Reviews in einer Datei, die das neue Review nicht abgeschlossen hat, zählt als nicht geprüft: Es ist nicht bekannt, dass er behoben ist.
Du fragst dich, was Sentinel in einer Authentifizierungsdatei prüft, wenn Shield installiert ist.
In deinem KI-Assistenten
Sentinel, führe bmad-plus review rules src/auth/login.ts aus und sag mir, welche Regeln und welche Compliance-Kontrollen gelten.
Das solltest du erhalten Der Befehl gibt den Fingerabdruck des Regelsatzes und die Schichten aus, aus denen er besteht (eingebaut, Pack-Dateien, Projektdatei), dann src/auth/login.ts gets N rule(s), eine Zeile je Regel mit ID, Gruppe, Schicht und Mustern und bei Shield-Regeln die Kontrollen wie ISO27001:A.8.5 und SOC2:CC6.1. Vom Projekt deaktivierte Regeln werden als deaktiviert aufgeführt. Es wird nichts geschrieben.
Das Repository liefert kopierfertige GitHub-Actions-Rezepte in docs/recipes/ci-review/: review-scope.yml versiegelt den Umfang und veröffentlicht die Checkliste (kein Agent, kein Modell); review-gate.yml lässt den auf einem selbst gehosteten Runner installierten Host-Agenten die Nachweise schreiben, prüft, dass sich außerhalb des Review-Ordners nichts geändert hat, verankert die Befunde und lässt die Prüfung bei incomplete oder offenen Befunden scheitern. Sie laufen nur für Pull Requests aus dem Repository selbst, nie aus Forks, und brauchen keinen in GitHub gespeicherten Modellschlüssel. In einem Skript genügen die drei Codes: 0 besteht, 1 heißt Befunde zum Lesen, 2 heißt, die Nachweise fehlen noch.