Referencia de bmad-plus review: sellar el alcance, anclar los hallazgos en el código, derivar un veredicto de la cobertura, reanudar, comparar y listar reglas, con opciones y códigos de salida.
bmad-plus review es la capa de evidencias de una revisión de código. No lee tu código con un modelo ni lo juzga: la lectura la hace el asistente (normalmente Sentinel). El comando fija lo que se revisa (el alcance), comprueba que cada hallazgo citado está de verdad en el código y deriva el veredicto de lo que se cubrió realmente, de modo que una revisión que se detuvo a medias nunca puede darse por limpia. Úsalo cuando quieras una revisión cuyo resultado se pueda comprobar, automatizar o usar para condicionar una pull request.
Nota· Qué significa clean
clean significa: ningún hallazgo abierto dentro de un alcance cubierto por completo. No demuestra que el código sea correcto, y una revisión sin hallazgos es válida. Una evidencia ausente, fallida o inválida da incomplete, nunca clean.
id da nombre a una revisión y se convierte en una carpeta: letras minúsculas, dígitos, puntos y guiones, empezando por letra o dígito, 81 caracteres como máximo (por ejemplo pr-42). rules es la única acción que recibe una ruta en lugar de un id.
Las seis acciones
Acción
Qué hace
Escribe
scope <id>
Fija lo que se revisa: los archivos modificados entre dos commits (o el árbol de trabajo), cuáles se seleccionan, qué reglas se aplican a cada uno y el plan de revisión.
scope.json, checklist.md
anchor <id>
Valida findings.json y localiza cada fragmento citado en el código del head. Los valores con aspecto de credencial se sustituyen por [REDACTED] en el registro escrito.
findings.anchored.json
gate <id>
Deriva el veredicto del alcance, la cobertura y los hallazgos anclados: clean, findings o incomplete.
opcionalmente un archivo de comprobación para CI
continue <id>
Lista lo que aún debe una revisión interrumpida, sobre el mismo alcance sellado. Se rechaza si el código o las reglas se movieron.
continue.json
compare <id> --since <earlier-id>
Clasifica los hallazgos de esta revisión frente a una anterior: nuevos, persistentes, resueltos, refutados, no revisados.
compare.json
rules [path]
Muestra el conjunto de reglas efectivo, o las reglas que recibiría una ruta dada.
nada
Opciones de review
Opción
Argumento
Por defecto
Qué hace
-d, --directory
<path>
carpeta actual
Carpeta del proyecto.
--dir
<path>
_bmad-output/review
Carpeta de revisiones dentro del proyecto. Cada revisión vive en <dir>/<id>/.
--base
<ref>
HEAD~1 (HEAD con --workspace)
Commit o rama base. El alcance parte de la base de fusión entre base y head.
--head
<ref>
HEAD
Commit o rama head.
--workspace
-
desactivado
Revisa el árbol de trabajo frente a la base, incluidos los archivos sin seguimiento.
--include
<glob>
ninguno
Solo revisa las rutas que coincidan. Repetible.
--exclude
<glob>
ninguno
Nunca revisa las rutas que coincidan. Repetible.
--effort
low|medium|high
medium
Profundidad de la revisión (ver más abajo).
--since
<id>
ninguno
Solo compare: la revisión anterior con la que comparar. Obligatoria ahí.
--emit-check
<file>
ninguno
Solo gate: escribe además el veredicto como resultado de comprobación JSON para CI. Debe ser un archivo .json.
review scope <id> escribe scope.json y una lista de comprobación de las reglas que se aplican a las rutas modificadas. El alcance tiene una huella: cualquier cambio posterior del código o de las reglas es detectable.
En la terminal del proyecto
npx bmad-plus review scope pr-42 --base main --effort high
02
Revisar y escribir las evidencias
El asistente lee los archivos, escribe findings.json (cada hallazgo cita su código textualmente, con categoría, gravedad, confianza y disposición) y coverage.json (cada archivo seleccionado termina como completed, failed o waived con un motivo). BMAD+ nunca llama a un modelo para esto.
03
Anclar los hallazgos
review anchor <id> encuentra cada fragmento citado en el código. Los números de línea escritos por un modelo no se usan nunca; solo cuenta la cita.
En la terminal del proyecto
npx bmad-plus review anchor pr-42
04
Pedir el veredicto
review gate <id> deriva clean, findings o incomplete. Añade --emit-check para obtener un documento JSON que un paso de CI pueda consumir.
El comando lee el historial de git y los archivos del proyecto (lanza git para rev-parse, diff, merge-base y ls-files) y las reglas de revisión. Solo escribe dentro de <dir>/<id>/, más el archivo de --emit-check. No abre ninguna conexión de red ni llama a ningún modelo.
Archivos de la carpeta de revisión
Archivo
Escrito por
Contenido
scope.json
scope
Base, head, base de fusión, archivos seleccionados y excluidos con motivos, reglas por archivo, unidades, plan, huella.
checklist.md
scope
Las reglas que se aplican a las rutas modificadas, como lista de comprobación para quien revisa.
findings.json
el asistente
Esquema bmad-plus/review-findings/1; cada hallazgo cita existing_code textualmente.
coverage.json
el asistente
Un elemento por archivo seleccionado (completed, failed, waived con motivo) y cómo terminó la ejecución (run.stop).
findings.anchored.json
anchor
Los hallazgos con sus líneas localizadas y los recuentos de localizados, ambiguos y no localizados.
continue.json
continue
El lote de trabajo pendiente.
compare.json
compare
Los hallazgos nuevos, persistentes, resueltos, refutados y no revisados.
Un valor desconocido es un error, nunca se corrige en silencio. Un hallazgo refutado conserva su refutación, uno confirmado necesita evidencia, un archivo fallido o descartado necesita un motivo. Solo run.stop: completed permite a la puerta llegar a un veredicto; cualquier otro motivo la mantiene incomplete. Una unidad que falla tres intentos seguidos se abandona y queda como fallida.
Una pasada es una lectura completa del alcance; las siguientes buscan lo que las anteriores dejaron pasar. El plan que imprime scope depende también del tamaño: desde 150 líneas modificadas quien revisa planifica antes de leer, y con más de una unidad y al menos 400 líneas modificadas las unidades pueden revisarse en paralelo. Una unidad agrupa como máximo 8 archivos y 400 líneas.
secret: .env*, claves y certificados (*.pem, *.key, *.p12, *.pfx, id_rsa*, id_ed25519*), .npmrc, .netrc y todo lo que esté bajo credentials/, .credentials/ o secrets/. Se comprueba antes de cualquier --include, así que ningún patrón puede traerlos.
binary, deleted, excluded-by-pattern (tu --exclude), not-included (fuera de tu --include).
generated-or-vendored: node_modules, dist, build, coverage, vendor, archivos minificados, source maps y archivos de bloqueo, salvo que un patrón --include los capture.
La propia carpeta de revisión: escribir hallazgos nunca cambia el alcance al que responden.
Una regla es una lista de comprobación en Markdown elegida según la ruta del archivo. Toda regla cuyos patrones coincidan se aplica al archivo, así que las reglas se suman. Ocho vienen con la CLI.
Reglas integradas
Id de regla
Grupo
Se aplica a
general
code
todos los archivos
javascript-typescript
code
js cjs mjs jsx ts cts mts tsx vue svelte
python
code
py pyi
sql-and-migrations
data
*.sql, carpetas de migraciones, *.prisma, schema.rb
shell
code
sh bash zsh ps1 psm1, Makefile
ci-workflows
delivery
GitHub Actions, GitLab CI, pipelines de Bitbucket y Azure
containers
delivery
Dockerfile, Containerfile, archivos compose, manifiestos de Kubernetes y Helm
Cuando el pack Shield está instalado se añaden seis reglas de cumplimiento (nunca reemplazan ni desactivan una integrada): shield-access-control, shield-personal-data, shield-cryptography, shield-logging, shield-ai-integrations y shield-change-and-supply-chain. Cada una nombra los controles que examina como MARCO:ID, por ejemplo ISO27001:A.8.5, SOC2:CC6.1, NIST-800-53:AC-3 o NIS2:Art.21(2)(i), y un hallazgo solo puede citar controles que examinen las reglas de su archivo.
Un proyecto añade, reemplaza (mismo id) o desactiva reglas en _bmad/review-rules.yaml. Sus archivos doc son Markdown, resueltos junto a ese archivo. Desactivar un id desconocido es un error.
findings.json es inválido, o al menos un hallazgo es ambiguo o no está localizado: cita un fragmento exacto más largo.
gate
0
clean.
gate
1
findings: hay al menos un hallazgo confirmado o sin resolver abierto.
gate
2
incomplete: un archivo no está contabilizado o falló, la evidencia es inválida o falta, la ejecución se detuvo antes de tiempo, o un hallazgo abierto no está anclado.
continue
0
Se escribió un lote de trabajo pendiente.
continue
3
moved: el código o las reglas cambiaron desde que se selló el alcance (o coverage.json es inválido).
cualquier acción
3
Error: acción desconocida, id inválido, falta el alcance o los hallazgos, fallo de git, JSON ilegible o inválido.
Estas transcripciones son simuladas: las líneas siguen las plantillas de mensajes del comando; los números y la huella son ilustrativos. Las rutas que imprime el comando real son absolutas.
Sellar un alcanceSimulado
$ 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
Transcripción ilustrativa, no capturada de una ejecución real. Fuente: tools/cli/commands/review.js (plantillas de mensajes de la acción scope)
Una puerta que aún no está listaSimulado
$ 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# Código de salida 2. La revisión debe aún dos archivos.
npx bmad-plus review gate pr-42
Transcripción ilustrativa, no capturada de una ejecución real. Fuente: tools/cli/commands/review.js (acción gate) y tools/cli/lib/review.js (motivos de reviewGate)
Un veredicto limpioSimulado
$ 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.# Código de salida 0.
Transcripción ilustrativa, no capturada de una ejecución real. Fuente: tools/cli/commands/review.js (acción gate)
El documento de --emit-check es estable (sin marca de tiempo, de modo que las mismas evidencias dan los mismos bytes). Lleva el estado, el código de salida, los motivos, los recuentos, el alcance al que responde, los hallazgos abiertos con sus líneas y un bloque github con la forma de la API de check-runs: conclusion (success o failure) y un output con un resumen en Markdown y hasta 50 anotaciones. Una revisión del árbol de trabajo escribe su comprobación en la carpeta de revisión o fuera del proyecto, para que no entre en el cambio del que informa.
Los errores imprimen review: <message> en el flujo de error (o un objeto JSON con status: "error" con --json) y salen con 3.
Mensajes
Mensaje
Causa
Qué hacer
unknown action "x" (scope, anchor, gate, continue, compare, rules)
La acción no es una de las seis.
Usa una de las acciones listadas.
a review id is required: lowercase letters, digits, dots and dashes
Falta el id, o tiene otros caracteres.
Pasa un id como pr-42.
no scope at <path> — run "bmad-plus review scope <id>" first
La carpeta de revisión no tiene scope.json.
Ejecuta review scope <id> con el mismo --dir.
invalid ref "..." o git rev-parse failed: ...
Un --base o --head que no resuelve a un commit.
Comprueba la referencia (tráela en CI); las que empiezan por - se rechazan.
git is unavailable: ...
git no está en el path del proceso.
Instala git o corrige el path.
effort must be one of low|medium|high
--effort desconocido.
Usa low, medium o high.
no findings at <path>
anchor o compare no encontró findings.json.
Escríbelo, aunque sea con una lista vacía.
--since <earlier review id> is required: ... / --since must name a different review
compare sin --since, o contra sí misma.
Pasa el id de la revisión anterior.
--emit-check writes a .json file / --emit-check must not overwrite the review evidence
La ruta no es un archivo .json, o es uno de los archivos de evidencia.
Elige otra ruta .json.
<id> cannot continue: the sealed scope no longer describes the code.
Código 3 de continue: el head se movió, cambiaron archivos o reglas.
Sella un nuevo alcance con las mismas opciones y luego review compare <new-id> --since <id>.
motivos de la puerta: no coverage.json: ..., no findings.json: ..., N selected file(s) never accounted for: ..., the review stopped before the end (budget): ...
La evidencia falta, es parcial o la ejecución se detuvo antes. Código 2.
Termina la revisión (continue), escribe los dos archivos y pon run.stop en completed solo si es verdad.
Revisar una pull request con evidencias comprobables#
Quieres que Sentinel revise los cambios de la rama frente a main y dé un veredicto fiable.
En tu asistente de IA
Sentinel, revisa esta rama frente a main. Si la CLI de BMAD+ está disponible, sella el alcance con bmad-plus review scope pr-42 --base main --effort high, cita cada hallazgo textualmente, luego ancla y pasa la puerta, e informa de la respuesta de la puerta sin mejorarla.
Lo que deberías obtener Sentinel ejecuta review scope, que escribe scope.json y checklist.md en _bmad-output/review/pr-42/. Revisa los archivos seleccionados, escribe findings.json y coverage.json, ejecuta review anchor (código 1 si una cita no se localiza) y review gate. Informa clean, findings o incomplete tal como lo imprimió la puerta. Una revisión detenida o parcial se declara incompleta, nunca limpia.
La sesión terminó antes de leer todos los archivos y coverage.json anota run.stop como interrupted.
En tu asistente de IA
Sentinel, continúa la revisión pr-42 donde se detuvo. Usa bmad-plus review continue pr-42 y haz solo lo que lista.
Lo que deberías obtenerreview continue escribe continue.json e imprime los archivos y unidades que faltan, los hallazgos que hay que volver a citar, las pasadas restantes y cualquier unidad abandonada tras tres intentos fallidos. Si el código o las reglas se movieron, se niega con código 3 y pide sellar un nuevo alcance y usar review compare. Cuando no queda nada, indica ejecutar review gate en cuanto coverage.json registre la ejecución como completada.
La autora subió correcciones. Sellaste un nuevo alcance pr-43 y terminaste la segunda revisión.
En tu asistente de IA
Sentinel, compara la revisión pr-43 con pr-42 usando bmad-plus review compare pr-43 --since pr-42 y dime qué es nuevo, qué persiste y qué está realmente resuelto.
Lo que deberías obtener El comando imprime pr-43 since pr-42: N new, N persisting, N resolved, N refuted, N not reviewed y escribe compare.json. Un hallazgo de la revisión anterior en un archivo que la nueva no completó cuenta como no revisado: no se sabe si está corregido.
Te preguntas qué comprobará Sentinel en un archivo de autenticación cuando Shield está instalado.
En tu asistente de IA
Sentinel, ejecuta bmad-plus review rules src/auth/login.ts y dime qué reglas y qué controles de cumplimiento se aplican.
Lo que deberías obtener El comando imprime la huella del conjunto de reglas y las capas que lo forman (integradas, archivos de pack, archivo del proyecto), luego src/auth/login.ts gets N rule(s), una línea por regla con su id, grupo, capa y patrones, y para las reglas de Shield los controles como ISO27001:A.8.5 y SOC2:CC6.1. Las reglas que el proyecto desactivó aparecen como desactivadas. No se escribe nada.
El repositorio incluye recetas de GitHub Actions listas para copiar en docs/recipes/ci-review/: review-scope.yml sella el alcance y publica la lista de comprobación (sin agente ni modelo); review-gate.yml hace que el agente anfitrión instalado en un runner autoalojado escriba las evidencias, verifica que nada cambió fuera de la carpeta de revisión, ancla los hallazgos y hace fallar la comprobación con incomplete o hallazgos abiertos. Solo se ejecutan para pull requests del propio repositorio, nunca de forks, y no necesitan ninguna clave de modelo guardada en GitHub. En un script bastan los tres códigos: 0 pasa, 1 significa hallazgos que leer, 2 significa que aún no hay evidencias.