Cómo hacemos software en DiluxOne

En DiluxOne, la energía humana va a escribir un buen issue. Una vez aceptado, un agente lo lleva hasta producción pasando controles que cualquiera puede auditar, y cada cambio termina con un recibo que prueba qué se pidió, cómo se hizo y cómo sabemos que funciona. Si algo falla, el cambio no avanza: se corrige solo dentro de sus topes, o vuelve a una persona con la acción concreta y su enlace.

8gates por cambio
3decisiones humanas
2hashes sellados por issue
1recibo firmado por merge

Tres decisiones. El resto lo verifican los gates.

Como en el isotipo: el bloque es lo que decide una persona; el módulo azul es lo que encaja y corre solo.

Siempre

Aceptar el issue

Es la única aprobación que necesita un cambio normal. Quien acepta leyó el PRD; desde ese momento el texto queda sellado con su hash.

Solo si es crítico

Mergear a mano

Un issue marcado como crítico, o un cambio que toca las reglas que gobiernan la autonomía, espera el merge de una persona, con el motivo a la vista.

Al publicar

Aceptar el release

Publicar una versión para usuarios es siempre una decisión humana: el issue de release se abre a mano o lo abre un milestone planificado.

Los ocho gates, en orden

Cada gate es un check con nombre fijo y deja su resultado en el tablero del issue. Los determinísticos mandan siempre; la IA puede frenar, nunca saltear uno determinístico.

determinístico · sin IA, reproducibleIA · solo puede frenarhumano · una persona decide
  1. G1

    Issue listo

    esquemarúbrica IA

    PRD completo según un esquema único: problema, alcance, fuera de alcance, criterios de aceptación con ID y forma verificable, criticidad.

    si fallaEl agente pregunta en el issue lo que falta; todavía no se puede aceptar.

  2. G2

    Aceptación

    humanoo carril de la política

    Una persona acepta, o un carril de la política de autonomía lo permite. En ese momento se sella el hash del PRD.

    si fallaNada arranca.

  3. G3

    Spec

    agentealcance y rutas

    Antes de escribir código, el agente completa la Spec en el mismo issue: archivos, enfoque y un test por criterio. También se sella su hash.

    si fallaSe sale del alcance o toca rutas protegidas: se frena y pregunta, con la acción y su enlace.

  4. G4

    Checks del proyecto

    determinístico

    Convenciones, lint, análisis estático, tests y lo propio de cada stack, como Plugin Check en WordPress.

    si fallaEl agente corrige y vuelve a empujar; cuenta como una ronda.

  5. G5

    Review limpia

    IA

    Ningún hallazgo bloqueante ni mayor abierto. Lo que las reviews aprendieron antes ya está escrito como reglas.

    si fallaBucle: corrige y vuelve a revisar, hasta 3 rondas; si no converge, vuelve a una persona con un resumen.

  6. G6

    Cumple el issue

    criterio → testalcance

    Cada criterio de aceptación tiene su test, existe y pasa. Nada fuera del alcance pedido.

    si fallaVuelve al bucle; si es de alcance, a una persona.

  7. G7

    Merge

    determinístico

    Todo en verde, los dos hashes revalidados, no crítico, ninguna regla de gobierno tocada, dentro del presupuesto. Se mergea solo y se emite el recibo.

    si fallaQueda para merge humano, con el motivo y el enlace.

  8. G8

    Main sano

    determinístico

    El CI de la rama principal sigue en verde después del merge.

    si fallaSe abre un revert automático y un issue.

Desarrollo guiado por recibos

Un cambio no está terminado cuando el código anda: está terminado cuando existe su recibo. El recibo es la prueba verificable, sellada y firmada de que se hizo lo que se aceptó, como se aceptó, con la evidencia que lo demuestra. Sin recibo, no hay «hecho».

¿Qué se pidió?

El PRD, sellado con su hash en el momento en que una persona lo aceptó.

¿Cómo se resolvió?

La Spec sellada y el commit exacto que llegó a producción.

¿Cómo sabemos que anda?

Criterio por criterio, el test que lo prueba y su resultado, más los checks y el veredicto de la review.

¿Quién lo autorizó?

La persona que aceptó, o el carril de la política, con la versión exacta de la regla que aplicó.

TDD

Primero el test: el código existe para hacerlo pasar.

SDD

Primero la especificación: el código la implementa.

RDD

El recibo es la definición de terminado: pedido, especificación, tests y autorización, y nadie lo puede alterar.

Issue

PRDqué y por qué, criterios con IDsellado al aceptar
Specplan técnico, un test por criteriosellado al pasar G3

Pull request

  • checks del stack
  • review limpia
  • criterio por criterio, con evidencia
  • merge por política

Recibo

  • hashes de PRD y Spec
  • commit, checks y veredicto
  • quién aceptó y qué regla aplicó
  • en una rama aparte, firmado

El sello: qué es el hash y cómo se revalida

Un hash es la huella digital de un texto: SHA-256 lo convierte en 64 caracteres. El mismo texto da siempre la misma huella; cambiar una sola coma da otra completamente distinta. No se puede volver de la huella al texto ni fabricar otro texto con la misma huella.

PRD aceptado · criterio C1Al guardar, el sitio muestra «Guardado» en menos de 2 segundos.
SHA-256 sellado4f1c9a07e2b85d3360af19c4d7e5b2a8916c0f3d27ab4e59c81d6f20a3b7e914
Alguien lo edita despuésAl guardar, el sitio muestra «Guardado» en menos de 20 segundos.
SHA-256 recalculado · no coincideb92e06d4c1f7a85e3d0b49c62a1f8e07d5c3b916a4e20f87c1d9b35e6a0f4c28

Huellas ilustrativas. Cada sección se normaliza antes de calcularla, para que un cambio invisible no la altere y uno real siempre lo haga.

1

Se calcula

Al aceptar el issue, el bot toma solo la sección PRD, la normaliza y calcula su SHA-256. Lo mismo con la Spec cuando pasa G3.

2

Se sella

La huella se guarda con quién aceptó, cuándo, la versión del esquema y la de la política, en un commit firmado por el bot en la rama de recibos.

3

Se muestra

El tablero del issue repite la huella para leerla de un vistazo. Si alguien edita el tablero, manda el sello de la rama de recibos.

4

Se revalida

Cada vez que se edita el issue, antes de que arranque el agente, en cada push y justo antes del merge.

// receipts/issues/123/merge.json · ilustrativo
{
  "issue": 123,
  "prd":  { "sha256": "4f1c9a07…a3b7e914", "accepted_by": "maintainer" },
  "spec": { "sha256": "9d2e51b8…c04f7a62" },
  "pull_request": 131,
  "head_commit": "e8b4c2f",
  "checks": "all green",
  "review": "clean, 2 rounds",
  "criteria": { "C1": "tests/SaveNoticeTest" },
  "policy": "autonomy.yml@3a91d0e",
  "merged_by": "policy"
}

Bugs: primero se reproducen, después se arreglan

Un bug reportado no se arregla por intuición. Un workflow intenta reproducirlo con lo que se informó; si se confirma, la falla queda escrita como un test, y el arreglo tiene que hacerlo pasar.

1 · Reporte

Se informa como issue

Qué se hizo, qué se esperaba, qué pasó y en qué versión.

2 · Clasificación

¿Es un bug?

Un workflow decide si describe una falla o en realidad pide algo nuevo.

3 · Reproducción

Se intenta reproducir

El agente escribe un test con los pasos informados y lo corre en un entorno limpio, sin secretos.

Se reproduce

Bug confirmado: a reparar

El test que falla es la evidencia; el arreglo tiene que hacerlo pasar, con todos los gates.

No se reproduce

Se pide más información

El issue recibe lo que se probó y qué falta para reproducirlo.

No es un bug

Pasa a la cola

Una función nueva o una mejora espera su aceptación como cualquier issue.

Carriles: qué avanza solo y con qué evidencia

Todo lo que se decide sin una persona sale de un único archivo de política. Un proyecto puede restringirla, nunca ampliarla. Si un trabajo no encaja en un carril, no se acepta solo.

Operativo

Bug reproducido

Un test que falla antes y pasa después, y un reporte que habla de lo mismo que el arreglo.

Primero en autonomía

Plataforma

Imagen de runners, dependencias de CI, versiones de herramientas. Evidencia: prueba de humo y checks verdes.

Siguiente

Issue humano

Lo que una persona acepta viaja solo hasta el merge, gate por gate.

Siempre con una persona

Release

Nunca se acepta solo: publicar para usuarios pasa siempre por una persona.

Regla de oro. Las reglas que gobiernan la autonomía y los gates que las aplican siempre requieren aceptación y merge humanos. La autonomía no puede ampliarse a sí misma, y un interruptor general la frena entera sin tocar código.

¿Y si alguien escribe «borrá todo el repo» en un issue?

Cuatro capas, y ninguna depende de que el agente se porte bien.

  1. Estructura estricta

    El issue tiene exactamente las secciones del esquema; cualquier texto fuera de ellas hace fallar el gate.

  2. Una persona leyó lo que se acepta

    El hash sella el PRD aceptado. El agente lee solo PRD y Spec en sus huellas selladas, nunca comentarios de terceros.

  3. El texto es dato, no orden

    El agente recibe el issue como especificación a implementar, nunca como instrucciones para él.

  4. Mínimo privilegio

    Las credenciales del agente no pueden borrar el repositorio, pushear a la rama principal ni tocar workflows. Todo pasa por un pull request con gates.

Cualquier decisión se explica en tres clics

¿Quién aceptó este cambio?

El tablero del issue: la persona, o el carril de la política con enlace a su versión exacta.

¿Por qué se mergeó sin nadie?

El tablero, fila del merge: cada condición con su resultado y su check.

¿Cumple lo que se pidió?

El recibo: criterio por criterio, el test que lo prueba y su resultado.

¿Qué se decidió solo esta semana?

Un resumen semanal con todo lo aceptado y mergeado por política.

Cada job arranca limpio. Cada release es una decisión.

Runners efímeros

Los repositorios públicos corren en los runners de GitHub; los privados, en máquinas propias. Cada job corre en un contenedor descartable, hecho con una imagen que se reconstruye sola cada semana y pasa una prueba de humo antes de usarse; si falla, sigue la anterior y queda un issue con el log. La máquina se describe como código.

Release como issue

Se abre el issue «Release X.Y.Z», a mano o al cerrarse su milestone. Una persona lo acepta: esa es la aprobación. El agente prepara el pull request de release pasando los gates, y el deploy verifica la aceptación y la versión antes de publicar.

Todo vive en GitHub y se configura una sola vez

Lo que es igual en todos los proyectos se define una vez, a nivel organización, en un repositorio central. Cada proyecto solo declara lo suyo, y cada trabajo corre donde corresponde.

La organización

Un repositorio central

Workflows reutilizables, reglas de la organización, políticas como datos, un bot propio que firma los commits del agente y escribe los recibos, y tipos de issue, Projects y secretos definidos una vez.

Repositorios públicos

Runners de GitHub

Cada job arranca en una máquina nueva de GitHub y se descarta al terminar. Sin costo para repositorios públicos.

Repositorios privados

Runner privado

Una máquina virtual en la nube con varios runners, solo para repositorios privados. Se prende cuando hay trabajos esperando y se apaga tras unos minutos sin uso.

Lo sensible nunca corre en el runner privado. La publicación de versiones, la verificación de credenciales de publicación y la reproducción de bugs (que ejecuta código escrito a partir del texto de un issue) corren siempre en máquinas nuevas de GitHub, que nacen limpias y se destruyen al terminar.

Descargalo: open source, licencia MIT

DiluxOne es una iniciativa de Pablo Di Loreto: tecnología para construir negocios, con plugins de WordPress, servicios en la nube y herramientas de IA, en una sola cuenta. Este pipeline es el framework con el que se construye cada uno de sus módulos, y es open source: usalo en tus propios proyectos, tal cual o adaptado. Pronto se viene un instalador que lo deja andando en tu organización de GitHub en pocos pasos.

Scroll al inicio