Revisión de código y aceptación humana

Dos tipos de prueba se suman a las pruebas automáticas. Una revisión de código verificable muestra qué se revisó, dónde está cada hallazgo y por qué se detuvo la revisión. Una ejecución de aceptación humana (recette en francés, la palabra que usa la herramienta para la página) muestra que una persona vio funcionar la cadena en pantalla. Ambas son evidencias que se pueden leer después y ambas se niegan a decir «no hay nada que señalar» cuando la evidencia está incompleta. Esta página es para revisores, responsables de equipo y quien decide si una versión sale.

Por qué una revisión necesita evidencias#

Una revisión escrita en prosa no se distingue de una que leyó doce archivos de cuarenta y no encontró nada. BMAD+ deja la revisión en sí al agente anfitrión (no llama a ningún modelo) y añade las tres cosas que solo el código puede garantizar.

1. Lo que debe revisarse se calcula, se sella con un hash y se lista, con un motivo nombrado para cada archivo excluido.
2. Dónde está un hallazgo sale de una cita literal del código, localizada por la CLI. Nunca se confía en el número de línea de un modelo.
3. El veredicto se deriva de la cobertura (cada archivo seleccionado contabilizado), nunca del número de hallazgos.

El recorrido de una revisión: scope, anchor, gate#

El identificador que pasas (demo-1 abajo) nombra una carpeta, _bmad-output/review/<id>/, donde vive toda la evidencia. El terminal muestra una ejecución real en un proyecto Git de dos commits: el segundo reescribió una función con un bucle desfasado en uno y además incluyó un archivo .env.

$ npx bmad-plus review scope demo-1 --base HEAD~1 --effort high
/work/demo/app4/_bmad-output/review/demo-1/scope.json
1 file(s) to review, 4 changed lines, 1 unit(s) — scope d29789f5ea88
  excluded 1 × secret
checklist: /work/demo/app4/_bmad-output/review/demo-1/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 rules src/cart.js
rule set 77b96cb6389d (built-in)
src/cart.js gets 2 rule(s):
  general                  code         builtin  **
  javascript-typescript    code         builtin  **/*.{js,cjs,mjs,jsx,ts,cts,mts,tsx} **/*.{vue,svelte}
$ npx bmad-plus review gate demo-1
demo-1: incomplete — coverage 0/1 completed (0 waived), 0 open finding(s), 0 refuted
  - no coverage.json: which files were reviewed is not established
  - no findings.json: write it even when there is nothing to report
  - 1 selected file(s) never accounted for: src/cart.js
# Código de salida 2. El archivo `.env` se excluyó como secreto antes de que ningún patrón pudiera devolverlo.

Ahora revisa el agente anfitrión. Lee scope.json y checklist.md (las reglas de revisión que se aplican a los archivos seleccionados, cada una una vez, con los archivos que cubre) y escribe dos archivos: findings.json y coverage.json. Un hallazgo cita el código; el archivo queda ligado al ámbito por su hash.

{
  "schema": "bmad-plus/review-findings/1",
  "scopeSha256": "d29789f5ea88...",
  "findings": [
    {
      "id": "F1",
      "path": "src/cart.js",
      "existing_code": "for (let i = 0; i <= items.length; i++) sum += items[i].price;",
      "content": "The loop runs one step past the end: items[items.length] is undefined, so reading .price throws.",
      "category": "correctness",
      "severity": "high",
      "confidence": "high",
      "disposition": "confirmed",
      "evidence": "With items = [{price: 1}], i reaches 1 and items[1] is undefined, so items[1].price throws.",
      "trigger": "Any non-empty cart.",
      "consequence": "total() throws a TypeError."
    }
  ]
}

{
  "schema": "bmad-plus/review-coverage/1",
  "scopeSha256": "d29789f5ea88...",
  "items": [ { "path": "src/cart.js", "outcome": "completed" } ]
}

$ npx bmad-plus review anchor demo-1
/work/demo/app4/_bmad-output/review/demo-1/findings.anchored.json — 1 located, 0 ambiguous, 0 unlocated
$ npx bmad-plus review gate demo-1 --emit-check _bmad-output/review/demo-1/check.json
demo-1: findings — coverage 1/1 completed (0 waived), 1 open finding(s), 0 refuted
  check: /work/demo/app4/_bmad-output/review/demo-1/check.json
# Código de salida 1. En el primer intento el hallazgo no tenía el campo evidence: el gate decía «incomplete» con el motivo «a confirmed finding needs evidence» hasta que se añadió.

Comandos y códigos de salida#

Qué se selecciona y qué se excluye#

Cada archivo excluido lleva un motivo: secret (.env*, claves, certificados, credentials/, secrets/, .npmrc, .netrc; se comprueba primero, ningún patrón de inclusión los devuelve), binary, deleted, excluded-by-pattern, generated-or-vendored (lockfiles, node_modules, dist, build, archivos minificados; un patrón de inclusión puede devolverlos) y not-included. Los archivos seleccionados se cortan en unidades ordenadas por directorio, de 8 archivos y 400 líneas cambiadas como máximo, para que revisores en paralelo se repartan el trabajo de forma determinista. La propia carpeta de revisión nunca forma parte del cambio.

--effort fija la profundidad antes de leer: low es una pasada; medium (por defecto) son dos pasadas y una de refutación; high son tres pasadas y una de refutación. Un cambio de 150 líneas o más se sondea antes de leerlo, y un cambio de 400 líneas o más con varias unidades se revisa en unidades paralelas. El esfuerzo queda sellado en la identidad del ámbito.

Cómo se deriva el veredicto#

• Los hallazgos usan vocabularios cerrados: gravedad critical, high, medium o low; confianza high, medium o low; disposición confirmed, refuted o unresolved; diez categorías (correctness, security, data-loss, concurrency, performance y otras). Un valor desconocido es un error, nunca se corrige. Un hallazgo refutado conserva su fundamento citado; uno confirmado conserva su evidencia.
• El anclaje compara líneas consecutivas completas tras normalizar los espacios. Una coincidencia es located, varias son ambiguas, ninguna es unlocated. Un hallazgo abierto no localizado mantiene el gate en incomplete: cita un extracto exacto más largo.
• Una revisión puede registrar por qué se detuvo (campo run.stop de coverage.json: completed, budget, time-limit, failure-streak, interrupted). Cualquier motivo salvo completed mantiene el gate en incomplete, aunque estén listados todos los archivos: una revisión detenida nunca es clean. Tres fallos seguidos en la misma unidad la abandonan para esta revisión.
• review continue se niega (salida 3, estado moved) cuando cambió el commit, las reglas o un archivo seleccionado; la respuesta es entonces un ámbito nuevo y review compare. En compare, un hallazgo se identifica por su ruta, categoría y cita normalizada, nunca por línea o id, y un hallazgo desaparecido cuenta como resuelto solo si la revisión posterior completó su archivo; si no, es «no revisado».
• Suelo de ocultación: antes de escribir findings.anchored.json, los valores parecidos a credenciales en los campos citados (bloques de clave privada, credenciales en URL, cabeceras de autorización, tokens bearer, valores de claves con nombre de credencial, formas conocidas de token) pasan a [REDACTED]. Es un suelo, no un escáner: un secreto sin forma reconocible puede pasar.

Las reglas integradas#

Una regla es un documento Markdown ligado a patrones de ruta; checklist.md lista cada regla que se aplica al menos a una ruta seleccionada, una vez, con los archivos que cubre. Una regla es una instrucción para mirar, no un hallazgo. Una regla puede nombrar un group (una familia) para que revisores paralelos tomen una unidad por grupo.

Un proyecto añade, reemplaza o desactiva reglas en _bmad/review-rules.yaml (esquema bmad-plus/review-rules/1): una regla es {id, title, globs, doc} con un documento Markdown dentro de _bmad/ de 64 KB como máximo, y disable: [id] quita una. Una clave desconocida, un id duplicado, un documento fuera de _bmad/ y desactivar una regla desconocida se rechazan, nunca se ignoran. El conjunto de reglas se incluye en el hash del ámbito, así que un archivo de hallazgos responde exactamente a un conjunto de reglas. Con el pack Shield instalado se suman seis reglas de cumplimiento: shield-access-control, shield-personal-data, shield-cryptography, shield-logging, shield-ai-integrations y shield-change-and-supply-chain. Cada una nombra los controles con los que se relaciona, como ISO27001:A.8.5, SOC2:CC6.1, GDPR:Art.32 o NIS2:Art.21(2)(d).

Poner puertas a las pull requests en CI#

Dos workflows de GitHub Actions listos para copiar están en docs/recipes/ci-review/. review-scope.yml sella el ámbito y publica la lista de comprobación en el resumen del job y como artefacto (sin agente ni modelo). review-gate.yml sella el ámbito, hace que el agente anfitrión instalado y con sesión iniciada en un runner autoalojado escriba findings.json y coverage.json, comprueba que nada salvo esos dos archivos cambió en la carpeta de revisión ni nada fuera de ella en el checkout, y luego ancla y pasa la puerta; el job falla ante una revisión incompleta o hallazgos abiertos. Ambos se ejecutan solo para pull requests del mismo repositorio, con permisos de solo lectura y las versiones fijadas. gate --emit-check escribe un documento cuyo bloque github tiene la forma de un check run, con como máximo 50 anotaciones en líneas ancladas (critical y high como fallo, medium como advertencia, low como aviso).

Sentinel, revisa mi trabajo sin confirmar solo en src/billing. Sella el ámbito con bmad-plus review scope billing-1 --base HEAD --workspace --include "src/billing/**" --effort medium y aplica las reglas de la lista de comprobación. Cita el código de cada hallazgo palabra por palabra, contabiliza cada archivo seleccionado en coverage.json, ejecuta review anchor y review gate, y dime exactamente qué archivos quedaron fuera y por qué. Si el gate responde incomplete, di qué falta en lugar de llamarlo clean.

La aceptación humana: la receta#

Las pruebas automáticas demuestran que las piezas se comportan. Una receta demuestra que una persona vio funcionar la cadena en pantalla: quien escribe, quien lee, la pantalla, el gesto. La habilidad de Core bmad-plus-uat (dirigida por Sentinel; comandos uat, alias recette) convierte una entrega en una página autónoma que un probador no técnico recorre paso a paso. Sus marcas se convierten en una ejecución JSON que el agente lee, clasifica y sobre la que aplica la puerta.

1. 01

   Escribir la especificación

   Un archivo JSON _bmad-output/uat/specs/<product>-<version>.json (esquema bmad-plus/uat-spec/2). Una secuencia real de pasos, cada uno con where, do y expect; un clic por línea do, un hecho verificable por expectativa; las etiquetas de pantalla palabra por palabra, copiadas del código; un testigo (aquello en lo que se apoya la prueba) con la consulta de solo lectura que demuestra su estado; writes: true más una comprobación verify en cada paso que persiste algo.

2. 02

   Comprobar y construir

   uat lint comprueba las etiquetas frente a tus archivos fuente, el marcado, el presupuesto (15 pasos y 30 minutos por defecto) y los testigos. uat build escribe la página, que lleva el SHA-256 de la especificación para que una ejecución diga siempre a qué revisión respondió.

   En la terminal del proyecto

   npx bmad-plus uat lint ID --src src
   npx bmad-plus uat build ID

3. 03

   Entregar la página

   En local, uat serve escucha solo en 127.0.0.1 y escribe las respuestas directamente en el proyecto en cada marca. En otro sitio, envía el archivo HTML; el probador guarda el JSON y tú lo cargas con uat import. En Claude Code o claude.ai la página puede publicarse como artefacto cuya base de datos conserva las respuestas. Di con claridad dónde viven las respuestas y qué pasos escriben de verdad.

   En la terminal del proyecto

   npx bmad-plus uat serve ID --port 4173

4. 04

   Leer la ejecución

   uat read imprime, por ejecución, el probador, las fechas, los recuentos de superados, fallidos, bloqueados, omitidos y pendientes, las advertencias de obsoleto o sin firmar, y cada fallo con el texto de la expectativa y la nota del probador.

   En la terminal del proyecto

   npx bmad-plus uat read ID

5. 05

   Clasificar, confirmar escrituras, pasar la puerta

   Clasifica cada expectativa fallida o bloqueada en triage/<id>.json, ejecuta en solo lectura el verify de cada paso de escritura superado y regístralo, y luego ejecuta uat gate.

   En la terminal del proyecto

   npx bmad-plus uat gate ID

$ npx bmad-plus uat lint example-1.0.0
example-1.0.0: 3 steps, 5 expectations, 8 on-screen labels
  no error
$ npx bmad-plus uat build example-1.0.0
/work/demo/app4/_bmad-output/uat/pages/uat-example-1.0.0.html — 3 steps, 83 KiB, spec a4a4850b284d
opens in English; the tester can switch to any of the 10 languages on the page
carries the 17 page guarantees: hidden-before-start, no-answer-before-run, verified-local-write, honest-save-status, save-on-every-change, restore-before-capabilities, newer-copy-wins, revision-guard, other-tab-notice, unreadable-draft-kept, progress-accessible, storage-explained, finished-is-not-accepted, unload-guard, utf8-and-escaped-diacritics, export-is-the-run, no-third-party-requests
$ npx bmad-plus uat gate example-1.0.0
example-1.0.0: awaiting
  - no run yet
# Código de salida 2: awaiting. El archivo de especificación es el ejemplo incluido en la habilidad uat de Core (templates/example-uat-spec.json).

Veredictos de la puerta, clases de clasificación y tipos de verificación#

Para cada fallo clasificado se registra una decisión: fix, amend-spec, remeasure, accept-risk (con un responsable nombrado) o ask-tester. Las comprobaciones verify tienen un tipo: sql, http, command o manual. Una marca en un paso de escritura no es una escritura: su verify se ejecuta en solo lectura y se registra en writeChecks, porque un paso marcado nueve veces de nueve resultó una vez no haber escrito nada. La puerta dice lo que establece: «human-observed: complete, current and triaged». No establece que el probador mirara en el lugar correcto.

Los ajustes uat#

Por qué una etiqueta de versión exige una ejecución aceptada#

BMAD+ se aplica la regla a sí mismo. El 2026-09-16 se descubrió que un comando (studio list) estaba roto en una instalación real, y llevaba semanas así. La suite de pruebas estaba en verde, el contrato de instalación pasaba y la CI estaba en verde. Lo que ninguno hacía era instalar el producto y usarlo como lo hace una persona. Desde la 0.17.0, una versión no llega a npm hasta que una persona haya instalado el candidato en una carpeta vacía, recorrido la página de la receta y cada fallo haya sido clasificado. La receta de la 0.23.0 se recorrió en un proyecto vacío el 2026-10-18: 28 expectativas de 28 superadas, con cada paso de escritura confirmado en solo lectura. Una primera pasada de esa receta había sacado a la luz un defecto de desinstalación que dejaba atrás las habilidades de diseño copiadas; se corrigió antes de la etiqueta. Los resultados en sí se quedan en la máquina del mantenedor, porque llevan rutas locales; el CHANGELOG registra el defecto que sacó a la luz.

• En el repositorio de BMAD+, npm run uat:spec falla cuando la versión de package.json no tiene receta, y npm run uat:gate falla salvo que la última ejecución esté terminada, responda a la revisión actual, no deje nada sin respuesta, tenga cada fallo clasificado con una decisión y cada paso de escritura superado confirmado en solo lectura. Un hook de pre-push impone ambos al empujar una etiqueta v*.
• Una expectativa bloqueada exige una repetición o una decisión explícita accept-risk de un responsable nombrado. Una receta marcada solo para que pase la puerta es peor que ninguna receta: si un paso no se puede recorrer, la respuesta es «blocked» con el motivo.
• Tu proyecto puede hacer lo mismo con dos scripts incluidos en la habilidad uat (templates/): uat-spec-present.mjs (se rechaza una versión sin receta, antes del push) y uat-release-gate.mjs (salida 0 superado, 1 fallido, 2 sin ejecución terminada, 3 otra revisión, 4 la puerta no pudo ejecutarse, lo cual no es un pase). BMAD+ no instala ningún hook de ciclo de vida: estos scripts son la capa que una instrucción o un agente no puede saltarse; conéctalos donde muerdan.

Sentinel, escribe la receta de aceptación (recette) del formulario de reservas que acabamos de entregar en preproducción. El probador trabaja en recepción, no es un desarrollador: un paso por gesto, un hecho verificable por expectativa, etiquetas de pantalla copiadas del código. Para el paso que crea una reserva, añade la consulta de solo lectura que ejecutarás después para demostrar que la fila existe. Ejecuta uat lint con --src src, luego uat build, y enséñame las garantías que lista el build. Dime el archivo o enlace, cuánto dura, qué pasos escriben y dónde se guardarán las respuestas.

Sentinel, lee la última ejecución de aceptación con uat read. Clasifica cada expectativa fallida o bloqueada como product, recipe, data o undecided en el archivo de clasificación y pregúntame por las que no sepas atribuir. Ejecuta en solo lectura la comprobación verify de cada paso de escritura superado y registra el resultado. Luego ejecuta uat gate e informa de su veredicto, del probador y de lo que sigue abierto. No marques como superado ningún paso no realizado.