bmad-plus review

bmad-plus review est la couche de preuves d’une revue de code. Il ne lit pas votre code avec un modèle et ne le juge pas : la lecture revient à l’assistant (souvent Sentinel). La commande fige ce qui est relu (le périmètre), vérifie que chaque constat cité se trouve vraiment dans le code, et tire le verdict de ce qui a réellement été couvert : une revue arrêtée à mi-chemin ne peut donc jamais être déclarée propre. Servez-vous-en quand vous voulez une revue dont le résultat se vérifie, se script ou conditionne une pull request.

Synopsis#

npx bmad-plus review <action> [id] [options]
npx bmad-plus review rules [path]
npx bmad-plus review compare <id> --since <earlier-id>

id nomme une revue et devient un dossier : lettres minuscules, chiffres, points et tirets, en commençant par une lettre ou un chiffre, 81 caractères au plus (par exemple pr-42). rules est la seule action qui prend un chemin au lieu d’un identifiant.

L’ordre du travail#

1. 01

   Sceller le périmètre

   review scope <id> écrit scope.json et une liste de contrôle des règles qui s’appliquent aux chemins modifiés. Le périmètre a une empreinte : tout changement ultérieur du code ou des règles est détectable.

   Dans le terminal du projet

   npx bmad-plus review scope pr-42 --base main --effort high

2. 02

   Relire et écrire les preuves

   L’assistant lit les fichiers, écrit findings.json (chaque constat cite son code mot pour mot, avec catégorie, gravité, confiance et disposition) et coverage.json (chaque fichier retenu finit completed, failed ou waived avec une raison). BMAD+ n’appelle jamais de modèle pour cela.

3. 03

   Ancrer les constats

   review anchor <id> retrouve chaque extrait cité dans le code. Les numéros de ligne écrits par un modèle ne servent jamais ; seule la citation compte.

   Dans le terminal du projet

   npx bmad-plus review anchor pr-42

4. 04

   Demander le verdict

   review gate <id> tire clean, findings ou incomplete. Ajoutez --emit-check pour obtenir un document JSON qu’une étape de CI peut consommer.

   Dans le terminal du projet

   npx bmad-plus review gate pr-42 --emit-check ci/review-check.json

5. 05

   Reprendre ou comparer au besoin

   review continue <id> après une interruption ; review compare <new-id> --since <id> quand le code a changé et que vous avez relu.

Ce qu’il lit et écrit#

La commande lit l’historique git et les fichiers du projet (elle lance git pour rev-parse, diff, merge-base et ls-files) ainsi que les règles de revue. Elle n’écrit que dans <dir>/<id>/, plus le fichier de --emit-check. Elle n’ouvre aucune connexion réseau et n’appelle aucun modèle.

Vocabulaires fermés#

Une valeur inconnue est une erreur, jamais corrigée en silence. Un constat réfuté garde sa réfutation, un constat confirmé exige une preuve, un fichier en échec ou écarté exige une raison. Seul run.stop: completed permet à la porte d’atteindre un verdict ; toute autre raison la laisse incomplete. Une unité qui échoue trois tentatives de suite est abandonnée et reste en échec.

Niveaux d’effort et plan#

Une passe est une lecture complète du périmètre ; les suivantes cherchent ce que les précédentes ont manqué. Le plan affiché par scope dépend aussi de la taille : à partir de 150 lignes modifiées, le relecteur planifie avant de lire, et avec plusieurs unités et au moins 400 lignes modifiées les unités peuvent être relues en parallèle. Une unité regroupe au plus 8 fichiers et 400 lignes.

Fichiers jamais retenus#

• secret : .env*, clés et certificats (*.pem, *.key, *.p12, *.pfx, id_rsa*, id_ed25519*), .npmrc, .netrc, et tout ce qui est sous credentials/, .credentials/ ou secrets/. Contrôlé avant tout --include : aucun motif ne peut les faire entrer.
• binary, deleted, excluded-by-pattern (votre --exclude), not-included (hors de votre --include).
• generated-or-vendored : node_modules, dist, build, coverage, vendor, fichiers minifiés, source maps et fichiers de verrouillage, sauf si un motif --include les capte.
• Le dossier de revue lui-même : écrire des constats ne change jamais le périmètre auquel ils répondent.

Règles de revue#

Une règle est une liste de contrôle Markdown choisie selon le chemin du fichier. Toute règle dont un motif correspond s’applique au fichier : les règles s’additionnent. Huit sont livrées avec la CLI.

Quand le pack Shield est installé, six règles de conformité s’ajoutent (elles ne remplacent ni ne désactivent jamais une règle intégrée) : shield-access-control, shield-personal-data, shield-cryptography, shield-logging, shield-ai-integrations et shield-change-and-supply-chain. Chacune nomme les contrôles qu’elle examine sous la forme CADRE:ID, par exemple ISO27001:A.8.5, SOC2:CC6.1, NIST-800-53:AC-3 ou NIS2:Art.21(2)(i), et un constat ne peut citer que des contrôles examinés par les règles de son fichier.

Un projet ajoute, remplace (même identifiant) ou désactive des règles dans _bmad/review-rules.yaml. Ses fichiers doc sont du Markdown, résolus à côté de ce fichier. Désactiver un identifiant inconnu est une erreur.

schema: bmad-plus/review-rules/1
rules:
  - id: billing-money
    title: Money amounts
    group: code
    globs: ['src/billing/**/*.ts']
    doc: review-rules/billing-money.md
disable:
  - python

Codes de sortie#

Exemple de sortie#

Ces transcriptions sont simulées : les lignes suivent les modèles de message de la commande, les nombres et l’empreinte sont illustratifs. Les chemins affichés par la vraie commande sont absolus.

$ npx bmad-plus review scope pr-42 --base main --effort high
<project>/_bmad-output/review/pr-42/scope.json
3 file(s) to review, 41 changed lines, 1 unit(s) — scope 3f9a1c0d52b7
  excluded 1 × generated-or-vendored
checklist: <project>/_bmad-output/review/pr-42/checklist.md
plan: high effort, 3 pass(es), refutation pass
Every selected file must end in coverage.json as completed, failed or waived (with a reason).

$ npx bmad-plus review gate pr-42
pr-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
# Code de sortie 2. La revue doit encore deux fichiers.

$ npx bmad-plus review gate pr-42 --emit-check ci/review-check.json
pr-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.
# Code de sortie 0.

Le document de --emit-check est stable (sans horodatage, donc les mêmes preuves donnent les mêmes octets). Il porte le statut, le code de sortie, les raisons, les nombres, le périmètre auquel il répond, les constats ouverts avec leurs lignes et un bloc github calqué sur l’API des check-runs : conclusion (success ou failure) et un output avec un résumé Markdown et jusqu’à 50 annotations. Une revue de l’arbre de travail écrit son contrôle dans le dossier de revue ou hors du projet, pour qu’il n’entre pas dans le changement dont il rend compte.

Erreurs et que faire#

Les erreurs affichent review: <message> sur le flux d’erreur (ou un objet JSON avec status: "error" sous --json) et sortent avec 3.

Exemples#

Sentinel, relis cette branche par rapport à main. Si la CLI BMAD+ est disponible, scelle le périmètre avec bmad-plus review scope pr-42 --base main --effort high, cite chaque constat mot pour mot, puis ancre-le et passe la porte, et rapporte la réponse de la porte sans la surévaluer.

Sentinel, reprends la revue pr-42 là où elle s’est arrêtée. Utilise bmad-plus review continue pr-42 et ne fais que ce qu’il liste.

Sentinel, compare la revue pr-43 à pr-42 avec bmad-plus review compare pr-43 --since pr-42 et dis-moi ce qui est nouveau, ce qui persiste et ce qui est vraiment résolu.

Sentinel, lance bmad-plus review rules src/auth/login.ts et dis-moi quelles règles et quels contrôles de conformité s’appliquent.

L’utiliser en CI#

Le dépôt fournit des recettes GitHub Actions prêtes à copier dans docs/recipes/ci-review/ : review-scope.yml scelle le périmètre et publie la liste de contrôle (ni agent ni modèle), review-gate.yml fait écrire les preuves par l’agent hôte installé sur un runner auto-hébergé, vérifie que rien n’a changé hors du dossier de revue, ancre les constats et fait échouer le contrôle sur incomplete ou des constats ouverts. Elles ne tournent que pour les pull requests du dépôt lui-même, jamais pour les forks, et n’exigent aucune clé de modèle stockée dans GitHub. Dans un script, les trois codes suffisent : 0 passe, 1 signifie des constats à lire, 2 signifie que les preuves ne sont pas encore là.