docs: un camino corto arriba del README que termine en el informe

[NicolasRocchia]

De dónde viene

Review externa de disensor (Grok 4.7), recibida el 2026-09-21; no está publicada. Su diagnóstico: "La superficie que ve una persona es un protocolo, no un producto." Y su pedido: un solo camino que produzca un informe real, con la primera pantalla como esa captura, y el protocolo más abajo para quien ya decidió usarlo. Contrastado contra 33222e6: el camino existe, pero no está a la vista.

Lo que hay hoy, verificado en 33222e6

El informe es el paso 12 de 16. ## Quick start (README.md:41-71) es un bloque de 16 líneas de comando sin narrativa: pip install, init, pin, reviewer suggest, round, new --round, y después prompt, pack, new sin ronda, validate, gate, report --open (:60), guide, guide --lang es, prompt --hash, hash. Los dos caminos (orquestado y manual) están intercalados en el mismo bloque, y el que llega no sabe cuál es el suyo.

## Trying it without touching your CI no llega al informe. Sus cinco comandos (README.md:80-84) terminan en gate --no-comment. El gate verde escribe el HTML, pero la sección no lo dice, y report no aparece.

reviewer add no está en el inicio. Quick start trae reviewer suggest (:51); el add que hace falta para que round corra vive en ## The orchestrated round (:146).

Lo más persuasivo está enterrado. Que el repo se juzga con su propio gate, la reproducción externa del tag 0.9.4 sin divergencias, y el DOI: la reproducción está en una oración adentro del párrafo de Status (README.md:591); el DOI es un badge. La review lo dice así: "Eso es más persuasivo que la lista de reglas."

La guía y el cierre de init siguen contando el camino a mano. El runbook que init instala como skill arranca por disensor round y disensor new --round (init.py:49-50, :92), pero la guía de llenado abre su sección "The round, and then the declaration" con disensor prompt como paso 1 y FILL_IN como paso 4 (GUIDE.md:18-31), y la última línea que init imprime manda a prompt (init.py:358). La segunda parte de la misma review lo dice desde el otro lado: un desarrollador que no quiere aprender familias, confinamiento, hardening y estados terminales no sostiene ese camino en el segundo pull request.

La primera línea ya es la correcta: "Your AI wrote the code. Another AI reviewed it." (README.md:3-4). El problema empieza después.

La propuesta

0. La guía y el "Next:" de init llevan primero el camino orquestado, como ya hace el runbook: round, new --round, llenar lo que quedó en FILL_IN, validate. El manual (prompt, pack, new sin ronda) queda como segundo camino en la misma sección, para quien no puede correr un revisor desde su máquina. GUIDE.es.md se espeja (tests/test_docs_sync.py:40-43 vigila el par).

1. Primera pantalla: la línea de apertura, el límite en una oración (el registro dirige la mirada humana; una declaración inventada con buena forma sigue necesitando muestreo; es la frase de rules.py:7-9), y un solo bloque de comandos que termina en report --open:

   pip install disensor
   disensor init --no-workflow
   disensor reviewer add codex --model <model> --yes
   disensor round --gate diff --generator-family anthropic --base main --head HEAD --result ../result.json
   disensor new --gate diff --level B --round ../result.json
   # fill the template; disensor guide says how
   disensor gate --no-comment --base main --head HEAD
   disensor report --open
   

   Ocho líneas, un camino. El manual (prompt, pack, new sin ronda, validate) y las utilidades (hash, guide, pin) van a una sección de referencia más abajo, no desaparecen.

2. La prueba arriba, no en Status: un párrafo corto después del bloque con las tres cosas que ya son ciertas y verificables (auto-gate, reproducción externa, DOI), con link a cada una.

3. ## Trying it without touching your CI termina en report --open, y dice que el gate verde lo escribe solo.

4. Captura: la vista Abierto del informe y el comentario del PR, como imagen. Decisión abierta: imágenes en el repo pesan y envejecen; una alternativa es linkear al informe real del repo o a disensor.dev.

Ataduras

tests/test_docs_sync.py:142-149 exige que los comandos de los fences bash sean idénticos y en el mismo orden entre README.md y README.es.md (los comentarios pueden diferir). tests/test_docs.py:34-42 exige que NicolasRocchia/disensor@vX.Y.Z aparezca en cada documento. Y cero guiones largos.

Lo que no se hace

No se toca el protocolo, ni el CLI, ni la ayuda. No se promete más que lo que el gate hace: la oración del límite va arriba justamente para eso. No se saca del README el detalle de reglas, compuertas y política: se baja.

Criterio de cierre

• En un repo limpio con un revisor registrado, el bloque de la primera pantalla corre de arriba a abajo sin pasos implícitos y termina con el HTML abierto.
• README.es.md tiene el espejo y pytest tests/test_docs.py tests/test_docs_sync.py está en verde.
• ## Trying it without touching your CI nombra report.
• disensor guide y el cierre de disensor init nombran round antes que prompt, en los dos idiomas de la guía.

Vecinos

• El changelog fuera de Status (docs: el diario de releases sale de ## Status a un CHANGELOG #68) libera el final del README; este issue arregla el principio. Van en PRs distintos.
• El idioma del informe (report: el informe sale en castellano fijo mientras el CLI habla inglés #70): la captura de la primera pantalla va a mostrar "Abierto" en un README inglés, que es exactamente README.md:195 hoy.

[NicolasRocchia]

El bloque de la propuesta, tal como está, no llega al informe. Corrido sobre a56d2f0 en un repositorio de prueba con cambios en una rama, un revisor falso registrado con --yes y el registro de revisores en un HOME temporal:

Paso	Resultado
disensor init --no-workflow	deja cuatro entradas sin commitear: .claude/, .gitignore, CLAUDE.md y disensor.config.json
disensor reviewer add <id> ... --yes	registra el revisor, sin consentimiento
disensor round ...	exit 1: el árbol no está limpio (lo que dejó init)
commit de lo de init, y round de nuevo	exit 4: el material no está autorizado
disensor reviewer consent <id>, y round de nuevo	exit 0

Le faltan dos pasos implícitos, que es justo lo que el criterio de cierre prohíbe:

1. Commitear lo que escribe init antes de la ronda. Es a propósito: la ronda de diff revisa commits que ya existen y no toca el trabajo sin commitear.
2. El consentimiento. add --yes no lo registra, aunque el mensaje que imprime sin --yes dice que la confirmación cubre el repositorio. Quedó en round: el modo degradado de un solo asistente existe por piezas (consentimiento, --generator-model, recetas que no fijan el modelo) #79, junto con el resto del camino de un solo asistente. Mientras no se resuelva, el bloque necesita disensor reviewer consent codex entre add y round.