# bmad-plus review

> 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.

Canonical: https://bmad-plus.rochetta.fr/es/docs/reference/cli-review/
Language: es
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT

Documentación de BMAD+ › [Referencia](https://bmad-plus.rochetta.fr/es/docs/reference/) › bmad-plus review

`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`.

<a id="synopsis"></a>
## Sinopsis

**En la terminal de tu proyecto**

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

`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`. |
| `--json` | - | desactivado | Salida legible por máquinas en lugar de texto. |

<a id="workflow"></a>
## El orden del trabajo

1. **Sellar el alcance** `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.

   ```sh
   npx bmad-plus review scope pr-42 --base main --effort high
   ```
2. **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.
3. **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.

   ```sh
   npx bmad-plus review anchor pr-42
   ```
4. **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.

   ```sh
   npx bmad-plus review gate pr-42 --emit-check ci/review-check.json
   ```
5. **Reanudar o comparar si hace falta** `review continue <id>` tras una interrupción; `review compare <new-id> --since <id>` cuando el código cambió y revisaste de nuevo.

<a id="reads-writes"></a>
## Qué lee y qué escribe

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. |

<a id="finding-vocabulary"></a>
### Vocabularios cerrados

**Valores permitidos en findings.json y coverage.json**

| Campo | Valores |
| --- | --- |
| `severity` | `critical`, `high`, `medium`, `low` |
| `category` | `correctness`, `security`, `data-loss`, `concurrency`, `performance`, `error-handling`, `compatibility`, `test-gap`, `maintainability`, `documentation` |
| `confidence` | `high`, `medium`, `low` |
| `disposition` | `confirmed`, `refuted`, `unresolved` |
| coverage `outcome` | `completed`, `failed`, `waived` |
| `run.stop` | `completed`, `budget`, `time-limit`, `failure-streak`, `interrupted` |

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.

<a id="effort"></a>
## Niveles de esfuerzo y plan

**--effort**

| Nivel | Pasadas | Pasada de refutación |
| --- | --- | --- |
| `low` | 1 | no |
| `medium` (por defecto) | 2 | sí |
| `high` | 3 | sí |

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.

<a id="exclusions"></a>
### Archivos que nunca se seleccionan

- `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.

<a id="rules"></a>
## Reglas de revisión

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 |
| `configuration` | delivery | `json yml yaml toml ini properties`, `package.json`, `pyproject.toml`, `requirements*.txt`, `go.mod`, `Cargo.toml`, `composer.json` |

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.

**_bmad/review-rules.yaml**

```yaml
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
```

<a id="exit-codes"></a>
## Códigos de salida

**Códigos de salida por acción**

| Acción | Código | Significado |
| --- | --- | --- |
| `scope`, `rules`, `compare` | 0 | Hecho. |
| `anchor` | 0 | Todos los hallazgos están localizados. |
| `anchor` | 1 | `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. |

<a id="real-output"></a>
## Ejemplo de salida

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 alcance** (Simulado)

```text
$ 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).
```

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á lista** (Simulado)

```text
$ 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
# Código de salida 2. La revisión debe aún dos archivos.
```

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 limpio** (Simulado)

```text
$ 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.
# 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.

<a id="errors"></a>
## Errores y qué hacer

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. |

<a id="examples"></a>
## Ejemplos

<a id="example-cli-review-seal-and-gate"></a>
### 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**

```text
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.

<a id="example-cli-review-resume"></a>
### Reanudar una revisión interrumpida

La sesión terminó antes de leer todos los archivos y coverage.json anota run.stop como interrupted.

**En tu asistente de IA**

```text
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 obtener** `review 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.

<a id="example-cli-review-compare"></a>
### Revisar de nuevo tras las correcciones

La autora subió correcciones. Sellaste un nuevo alcance pr-43 y terminaste la segunda revisión.

**En tu asistente de IA**

```text
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.

<a id="example-cli-review-rules"></a>
### Ver qué reglas se aplican a un archivo

Te preguntas qué comprobará Sentinel en un archivo de autenticación cuando Shield está instalado.

**En tu asistente de IA**

```text
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.

<a id="ci"></a>
## Usarlo en CI

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.

**Véase también**

- [Códigos de salida de todos los comandos](https://bmad-plus.rochetta.fr/es/docs/reference/cli-overview/#exit-codes)
- [assurance: casos de evidencias para Shield](https://bmad-plus.rochetta.fr/es/docs/reference/cli-assurance/)
- [uat: recetas de aceptación humana](https://bmad-plus.rochetta.fr/es/docs/reference/cli-uat/)
- [nexus: ejecuciones duraderas y verificación independiente](https://bmad-plus.rochetta.fr/es/docs/reference/cli-nexus/)
- [Solución de problemas](https://bmad-plus.rochetta.fr/es/docs/faq/troubleshooting/)

[Documentación de BMAD+](https://bmad-plus.rochetta.fr/es/docs/) · [Referencia](https://bmad-plus.rochetta.fr/es/docs/reference/)

[Código en GitHub](https://github.com/lrochetta/BMAD-PLUS)