RDD y su relación con ODD

Objetivos

• Distinguir ODD de RDD y conocer sus puntos de contacto.
• Interpretar la salida de gentle-ai review assess.
• Usar el interruptor de RDD.
• Elegir lentes según lo que se tocó.
• Reconocer el ciclo de una revisión y su frontera con la entrega.

Este capítulo cubre lo necesario para trabajar con ODD. El contrato completo está en docs/review-integration.md.

---

Qué es RDD

Receipt-Driven Development (RDD) revisa un candidato terminado sin hacerse cargo de la entrega. La crónica del proyecto lo reduce a una oración: cuando cambias algo importante, alguien lo revisa antes de que salga. El reto, dice, es que no estorbe.

Su punto central es que una revisión no puede desviarse: el candidato se congela antes de que nadie lo lea, de modo que la evidencia pertenece a la versión exacta que vas a usar.

	ODD	RDD
Qué es	Flujo de trabajo	Revisión independiente
Quién lo controla	Corre siempre	Un interruptor del usuario
Quién manda	Guía para el modelo	El binario gentle-ai
Runtimes	Todos	Claude Code, Codex, OpenCode y Pi
Autoriza la entrega	No	No

ODD nunca enciende RDD. Una lista de tareas o un desafío de supuestos tampoco lo activa ni lo sustituye.

---

El interruptor

RDD está activo por defecto y es opt-out. Sin preferencia guardada, el estado informa on decidido por default, sin registrar ninguna decisión tuya.

Comando	Efecto
gentle-ai review mode status --cwd <repo>	Informa las fuentes y el modo efectivo, sin cambiar nada
gentle-ai review mode disable --cwd <repo>	Apaga globalmente
gentle-ai review mode disable --scope clone --cwd <repo>	Apaga solo en este clon
gentle-ai review mode enable --scope global --cwd <repo>	Activa globalmente para candidatos futuros
gentle-ai review mode enable --scope clone --cwd <repo>	Quita el apagado de este clon. Un OFF global sigue ganando

Cualquier fuente apagada gana. Un clon puede optar por salir, pero no puede exigir revisión.

Lo que el agente debe hacer

Estas instrucciones se instalan en cada runtime con RDD:

• Si pides dejar de usarlo, ejecuta disable, sin discutir, evitar la orden ni proponer alternativas primero.
• Mientras está apagado, sigue implementando normalmente: no inicia revisiones, no reintenta y no lo reactiva.
• La entrega con el interruptor apagado sigue la política ordinaria del repositorio e informa disabled/unmanaged, nunca una aprobación fabricada.
• Nunca cambia el modo por su cuenta ni guarda una preferencia solo porque el valor por defecto es activo.

Al reactivarlo, se revalida el candidato actual en lugar de retomar obligaciones antiguas.

---

review assess: la evaluación de solo lectura

Este comando clasifica el riesgo con la misma lógica que usaría una revisión, sin crear autoridad, linaje ni datos. Funciona igual con RDD activo o apagado.

gentle-ai review assess --cwd <repo> --agent <runtime> \
  --base-ref <último límite revisado> --committed-only --json

{
  "schema": "gentle-ai.review-assessment/v1",
  "risk": "high",
  "reasons": [{"code": "service_token", "path": "internal/auth/service-token.go"}],
  "changed_paths": 1,
  "changed_lines": 43,
  "candidate": {"kind": "base-diff", "base_ref": "15ea98ed", "consumed": false},
  "review_due": true,
  "review_due_reason": "high_risk",
  "next_transition": {
    "operation": "review.status",
    "command": "gentle-ai review status --cwd <repo> --contract gentle-ai.review-integration/v2 --agent claude-code --next-transition --base-ref 15ea98ed --committed-only"
  }
}

review_due: lo que realmente devuelve el código

La función reviewAssessDue tiene cuatro casos, evaluados en este orden:

Condición	review_due	review_due_reason	Conducta
El candidato ya se consumió	false	already_reviewed	Este rango exacto ya tiene autoridad terminal
risk es high	true	high_risk	Ejecutar next_transition.command textualmente
risk es medium	false	under_budget	Queda pendiente en la porción
risk es passive	false	passive	No necesita revisión y el límite avanza

Nota sobre la documentación. docs/usage.md todavía menciona slice_budget_reached como motivo de review_due: true. Sigue existiendo como constante en internal/cli/review_assess.go, pero el código ya no la devuelve: un candidato medium responde under_budget sean cuantas sean sus líneas. Es una decisión registrada en odd/tasks/verify-always-rdd-high.md. Las notas de v4.1.0 y docs/review-integration.md lo confirman con esta explicación: el tamaño es un presupuesto del prompt del revisor, no un riesgo.

El texto instalado también dice que under_budget queda pendiente “hasta que un commit posterior alcance el presupuesto”. Con el código vigente, un commit medium no llega a estar debido por tamaño.

También se revisa a pedido

Un candidato medium o passive puede revisarse si lo pides explícitamente. El automatismo solo cubre high.

Escalar

El agente puede subir el riesgo a high citando un punto de alto riesgo. Nunca puede bajarlo.

gentle-ai review assess --cwd <repo> --json \
  --escalate-item 3 --escalate-reason "cambia el formato de state.json"

El par de flags va junto. El punto es un entero del 1 al 6 y el motivo tiene como máximo 500 bytes, en una línea. La salida agrega un motivo agent_escalation.

Hay un detalle que se omite con facilidad: el next_transition que devuelve review assess es un preflight de review status, no un START, y no lleva el escalamiento. El mismo par de flags se pasa también a START. Sin eso, la revisión queda debida pero corre con el nivel nativo.

Si la evaluación falla

Un fallo nunca implica riesgo bajo. Si no se puede construir el candidato, el comando falla de forma cerrada y nombra una continuación ejecutable. El host trata ese fallo como un high.

---

El bucle dentro de ODD

Este es el punto de contacto entre ambos sistemas, después de cada commit por unidad cuando RDD está activo:

flowchart TD
    A["Commit por unidad"] --> B["review assess<br/>--base-ref último límite revisado"]
    B --> C{"review_due"}
    C -->|"true: high_risk"| D["¿Hay commits under_budget pendientes?"]
    D -->|"Sí"| E["Cerrar antes la porción abierta<br/>y revisarla como porción"]
    D -->|"No"| F["Ejecutar next_transition.command<br/>con las lentes elegidas"]
    E --> F
    F --> G["Seguir las transiciones"]
    G --> H["Reconocido: el límite avanza a este commit"]
    C -->|"false: passive"| I["El límite avanza"]
    C -->|"false: under_budget"| J["Queda pendiente en la porción"]
    C -->|"false: already_reviewed"| K["Ya cubierto"]
    H --> L["Registrar nivel y resultado en el documento"]
    I --> L
    J --> L
    K --> L

En el documento de feature se registra, por commit, el nivel y el resultado: concedido, declinado, pasivo, bajo presupuesto, ya revisado o no disponible.

---

Las lentes 4R

La revisión mira el cambio con hasta cuatro lentes independientes. Se juzga por la consecuencia, no por los nombres ni la cantidad de archivos.

Lente	Corresponde cuando
risk	Un error podría exponer, perder o cambiar de forma irreversible algo: datos almacenados, credenciales, permisos, guardas o contratos
resilience	Cambia el comportamiento ante fallas: errores, reintentos, timeouts, escrituras parciales, carga o concurrencia
readability	Cambia lo que otros leen o de lo que dependen: API públicas, salida y mensajes de comandos, documentación o estructura del código
reliability	Cambia lógica o comportamiento observable que las pruebas deberían fijar

Elegir lentes

gentle-ai review status --cwd <repo> --contract gentle-ai.review-integration/v2 \
  --agent claude-code --next-transition --base-ref <ref> --committed-only \
  --lenses risk,reliability --lenses-reason "cambia la validación del token y su lógica"

• Se eligen todas las lentes pertinentes y solo esas. Un cambio con una sola preocupación paga una lente.
• El motivo es una línea que nombra qué se tocó y cómo.
• Nunca se eligen lentes para volver a comprobar las especificaciones. Eso le corresponde al verificador.

Sin los flags, START usa el valor por defecto del nivel: una lente review-reliability para medium y las cuatro para high.

Nota sobre la documentación. odd/tasks/verify-always-rdd-high.md registra una decisión de rechazar un START sin selección de lentes. Esa tarea, B1, sigue sin marcar en el documento, y docs/review-integration.md describe el comportamiento vigente con valores por defecto.

---

El ciclo de una revisión

flowchart LR
    A["STATUS sin selector<br/>preflight"] --> B["START exacto<br/>congela el candidato"]
    B --> C["Colección de revisores"]
    C --> D["approved"]
    D --> E["acknowledge-approved<br/>quema la autoridad"]
    E --> F["Política ordinaria del repositorio"]

Ideas clave:

• Tokens exactos. El parent conserva el linaje, la revisión y el destino que devuelve START, y los usa tal cual en cada llamada. No se reconstruyen comandos a partir de la prosa.
• Contexto inmutable. Los revisores reciben contexto congelado, nunca el estado vivo del espacio de trabajo.
• Una corrección acotada. Solo los hallazgos severos causados por el candidato pueden bloquear. Hay una corrección acotada y un validador con acceso a los árboles congelados.
• Quemar. Tras aprobarse, ejecutar el acknowledge-approved exacto elimina la autoridad y los artefactos. No queda recibo ni autoridad de entrega.

Consentimiento

Un START de riesgo medio o alto puede devolver un sobre de consentimiento. El orquestador lo transmite completo, tal como vimos en el capítulo 9, y ejecuta solo la invocación que elijas.

• El modo global permite la revisión, pero no concede el consentimiento por candidato.
• Declinar un candidato no es el interruptor: se sigue con la política ordinaria.
• En sesiones interactivas el consentimiento se pide una vez por clon, y “not now” aplica solo a ese candidato.

Qué nunca hace

Una revisión aprobada no autoriza commit, push, PR, lanzamiento ni archivo. review validate y sus puertas nombradas son solo informativos: invalidated/unmanaged con RDD activo y disabled/unmanaged con RDD apagado.

---

La frontera con la verificación

Una aclaración frecuente: RDD no reemplaza a la verificación. El nivel de verificación se aplica con RDD activo o inactivo, y el verificador del nivel corre antes de la revisión. Si declinas el consentimiento, el clon está apagado o se rechaza un START, la verificación no cambia.

---

Actividad

Sin ejecutar nada todavía, escribe qué harías con estas tres salidas de review assess tras un commit:

1. risk: medium, changed_lines: 900, review_due: false, under_budget.
2. risk: high, review_due: true, con dos commits under_budget pendientes.
3. El comando falla con una referencia de base irresoluble.

Una posible solución

1. Registrar el motivo y continuar. El tamaño no vuelve debida una revisión. Sí importa para el presupuesto de entrega de la rama, que es otro mecanismo.
2. Cerrar primero la porción abierta y revisarla como tal, y luego revisar el commit de alto riesgo solo, contra el nuevo límite.
3. Seguir la continuación nombrada por el comando. Tratarlo como high, nunca como bajo riesgo.

---

Autoevaluación

1. Un candidato medium de 2000 líneas sin consumir devuelve:

   • A. review_due: false, under_budget
   • B. review_due: true, slice_budget_reached
   • C. review_due: true, high_risk
   • D. Un error

2. Pides “deja de usar RDD”. ¿Qué debe hacer el agente?

   • A. Explicar por qué conviene mantenerlo
   • B. Proponer solo apagarlo en este clon
   • C. Apagarlo durante esta sesión y reactivarlo después
   • D. Ejecutar disable sin discutir

3. ¿Qué lente corresponde a un cambio en reintentos y timeouts?

   • A. readability
   • B. resilience
   • C. risk
   • D. Ninguna, por no tocar datos

4. Una revisión termina approved. ¿Qué autoriza?

   • A. El merge
   • B. El push
   • C. Nada en la entrega: sigue la política ordinaria
   • D. La publicación de la versión

Respuestas

1. A. Así responde reviewAssessDue, según el caso medium del código.
2. D. Es la instrucción textual del bloque instalado.
3. B. Según las definiciones de lentes.
4. C. La aprobación es informativa respecto de la entrega.

Lista de control

• Sé qué runtimes reciben RDD y quién lo controla.
• Interpreto review_due sin confiar en la mención a slice_budget_reached.
• Puedo escalar con --escalate-item y justificar lentes.
• Entiendo por qué la aprobación no autoriza la entrega.

Fuentes

docs/review-integration.md, docs/architecture/organic-rdd.md, docs/architecture/the-organic-rdd-story.md, docs/trigger-rules.md, internal/cli/review_assess.go, internal/model/rdd.go, internal/components/agentguidance/routing.go, internal/assets/skills/_shared/review-ledger-contract.md, odd/tasks/verify-always-rdd-high.md, notas de v4.1.0.