Kronuz/campaign

Campaña

El líder (la sesión principal) convierte los objetivos del propietario en misiones. Un agente contribuyente completa cada misión en su propia rama; el trabajo de máquina va a una cola de trabajos que lo ejecuta en commits exactos mientras ningún agente espera. Un agente revisor examina una misión desde un contexto nuevo cuando su riesgo lo requiere. campaign land coloca una misión en main solo cuando sus verificaciones pasaron en ese código exacto, cada criterio tiene la evidencia que nombra, y cada revisión requerida fue aceptada para el código que vio. Todo lo que importa está en el repositorio, por lo que cualquier agente, incluido el líder, puede ser reemplazado.

goals ─► PLAN ─► quests ─► campaign start ─► contributor ─► jobs (quiet) ─► evidence
                                                  │                              │
                                                  └─► reviewer (by risk) ─► accept ─► campaign land

Invariantes

1. Evidencia, no narrativa. Una verificación cuenta solo cuando un trabajo la ejecutó en el código que se está fusionando; una línea de diario o la palabra de un revisor nunca es una prueba verde.
2. Un escritor por conjunto de archivos. campaign start rechaza conjuntos de archivos superpuestos; land rechaza cambios fuera del conjunto de la misión y ediciones a los archivos del líder.
3. Criterios antes que código. El líder escribe los criterios de aceptación de cada misión y la evidencia que cada uno necesita; los contribuyentes nunca los editan, y un archivo de misión modificado invalida aceptaciones anteriores.
4. La revisión sigue al riesgo. Un revisor nuevo por riesgo que lo necesite; una aceptación cubre el código que su revisión vio y el contenido exacto de la revisión.
5. Nada se debilita en silencio. Reducir un riesgo, eliminar un lente o una verificación, renunciar a una revisión, fusionar sin CI o registrar una fusión hecha a mano necesita una razón, que la herramienta registra.
6. El estado vive en archivos. .campaign/<campaign>/ y git contienen cómo se ejecuta la campaña; lo que es el producto va a docs/ del repositorio que describe.
7. Los agentes nunca esperan en las máquinas, y las mediciones nunca se ejecutan sin aislamiento.
8. El propietario decide los objetivos, el alcance y cualquier eliminación o reducción del comportamiento visible para el usuario. El líder decide el resto y lo registra en PLAN.md. Campaña nunca alquila máquinas ni crea ningún otro recurso facturable.

Roles

Rol	Hace	Escribe
Propietario (una persona)	Objetivos, no-objetivos, decisiones reservadas	PLAN.md objetivos
Líder (la sesión principal)	Planifica misiones, lanza agentes, acepta revisiones, fusiona, informa al propietario	state.json (solo a través de campaign), archivos de misión, PLAN.md, main
Contribuyente (agente campaign-contributor)	Una misión o tarea, según su asignación	su rama y diario
Revisor (agente campaign-reviewer)	Una misión a través de un lente, desde un contexto nuevo	un archivo de revisión

La asignación de un contribuyente nombra el tipo de trabajo; cada una excepto implementación tiene un método en references/assignments/<name>.md. El líder nombra la asignación, el nivel del modelo y el esfuerzo en cada lanzamiento, eligiendo por el trabajo, nunca por hábito:

Asignación	Para	Nivel, esfuerzo
implementación	características y correcciones con criterios concretos	económico, medio para riesgo bajo y normal; fuerte, alto para riesgo alto y crítico, o después de que un intento económico se estanque
diseño	listas de misiones para planes consecuentes; formatos, protocolos, durabilidad, concurrencia	fuerte, alto; máximo para un diseño a punto de congelarse
investigación	raramente: el mecanismo en sí es el límite	fuerte, máximo
rendimiento	perfilado y optimización	fuerte, alto
exploración	un objetivo de un lote de exploración, o una pregunta rápida	económico, medio
documentación	docs, guías, READMEs	económico, medio
mantenimiento	un cambio mecánico a través de repositorios	económico, medio

Los revisores usan el nivel fuerte con esfuerzo alto (máximo para misiones críticas); para misiones críticas y el desafío del plan, un revisor de otra familia de modelos cuando el arnés ofrece una. Los modelos de cada arnés para los niveles están en references/harness.md. Cambia un valor predeterminado según los resultados (campaign usage, criterios cumplidos, retrabajo), no solo por precio. El líder hace pequeñas ediciones él mismo (una corrección de cinco líneas, un conflicto trivial): un lanzamiento cuesta más.

Iniciar una campaña

1. En el checkout principal del repositorio base: campaign init --name NOMBRE [--ci github]. El propietario escribe Objetivos, No-objetivos, Restricciones y Decisiones reservadas en .campaign/<campaign>/PLAN.md.
2. Divide los objetivos en misiones: campaign new ID --title T --risk R --files GLOBS [--needs IDS] [--after IDS] [--provides C] [--consumes C] [--milestone M] --check NAME[:LEVEL[:MIN]]=CMD. Completa cada archivo de misión (.campaign/<campaign>/quests/ID.md): resultado, criterios A1... cada uno con la evidencia que necesita (Evidencia, más abajo), contratos, decisiones, lo que puede fusionarse anticipadamente.
3. Cuando la arquitectura es consecuente, un revisor (lente design) desafía el plan y la lista de misiones antes de que se construya algo. Esta es la única revisión por la que vale la pena esperar.

Misiones

• Tamaño: el cambio más pequeño que ofrece un comportamiento completo y significativo que un revisor pueda tener en mente, generalmente de unos cientos a ~1,500 líneas. Divide las más grandes; pliega un cambio que no merece su propia fusión en la misión a la que sirve.
• needs debe fusionarse antes de que una misión comience; after debe fusionarse antes de que ella se fusione. Una misión puede comenzar contra una dependencia after solo porque el archivo de esa dependencia fija el contrato.
• Contratos (--provides, --consumes) nombran APIs, formatos y protocolos, por lo que campaign check ve dos misiones que tocan uno.
• Tareas: escritores paralelos dentro de una misión (campaign start ID --task T --files GLOBS), fusionados en la rama de la misión por el líder. La misión aún se revisa una vez.
• Incrementos: campaign land ID --upto COMMIT --reason R fusiona un prefijo que el archivo de la misión "Puede fusionarse anticipadamente" permite (refactorizaciones que preservan comportamiento, pruebas, APIs internas no utilizadas, código detrás de un interruptor deshabilitado). Nunca anticipadamente: bytes en disco o en el cable, API pública, comportamiento visible para el usuario, o la parte para la que existe la revisión.
• Trabajo entre repositorios son varias misiones (--repo PATH) ordenadas por after, con un trabajo de integración que fija el commit de cada repositorio (--ref NAME=PATH@REF). La fusión es ordenada, nunca atómica: cada estado intermedio debe funcionar.
• Mensajes: un agente con un hallazgo para una misión en la que no está trabajando, en cualquier campaña de la máquina, envía campaign message NOMBRE:ID "texto" --from QUIEN. La misión no puede fusionarse hasta que uno de sus diarios lo responda por su id (msg-N) o el líder lo cierre (campaign message ID --close msg-N --reason R); NOMBRE: escribe al líder de esa campaña y nunca bloquea una fusión. Detalles, y otras máquinas: references/host.md, Mensajes.
• Cambios de alcance: una nueva solicitud va primero al archivo de misión (un criterio, o su propia misión si puede fusionarse sola), luego al contribuyente; el trabajo superado es campaign set ID status=dropped reason=....

Camino directo primero

Solo lo que decide el siguiente paso lo bloquea. Las verificaciones de puerta de una misión (--check: la compilación, las pruebas y la evidencia que su riesgo requiere) bloquean su fusión. Sus verificaciones diferidas (--later: otras plataformas, soaking largos, matrices completas, fuzzing extendido) se ponen en cola con baja prioridad en el código fusionado y deben estar en verde antes de que el hito se cierre. Una en rojo es un error en campaign check: corrige hacia adelante o revierte, luego campaign verify ID --deferred las vuelve a ejecutar en main. La evidencia que un riesgo alto o crítico necesita (TSan para concurrencia, fuzzing para un decodificador, el modelo de fallo para durabilidad) es siempre una verificación de puerta. Los flujos de trabajo de CI lentos pueden hacerse no bloqueantes de la misma manera (campaign config ci_later=NOMBRE,...).

Ejecutar una misión

1. campaign start ID crea quest/<campaign>/ID en su propio árbol de trabajo con un diario. Lanza un contribuyente en segundo plano, para que pueda reanudarse mediante mensajes, con el prompt "Contribuyente" (references/prompts.md); ejecuta misiones en paralelo solo cuando están listas, son disjuntas y no esperan en la misma máquina.
2. El contribuyente trabaja en su árbol de trabajo, mantiene su diario actualizado y produce evidencia como trabajos: campaign job submit --quest ID --level L --minutes M -- CMD y campaign verify ID. Cuando solo quedan trabajos, registra sus ids y finaliza su turno.
3. El líder espera con un campaign wait --commits en segundo plano (sin tokens hasta que termine un trabajo, se mueva una rama o llegue un mensaje), luego reanuda al contribuyente mediante mensaje mientras su contexto es pequeño (aproximadamente 150k tokens). Un contexto más grande, o un arnés que no pueda reanudarlo, obtiene un contribuyente nuevo con el prompt "Reanudar", que reconstruye desde el diario y los registros de trabajo.
4. Cuando el diario dice "listo para revisión", el líder establece status=review y lanza los revisores que el riesgo requiere; cada uno escribe .campaign/<campaign>/reviews/ID-LENS.md. El líder transmite los hallazgos bloqueantes al contribuyente por id.
5. campaign accept ID LENS una vez que una revisión aprueba, o después de CAMBIOS con los trabajos de confirmación (Riesgo y revisión); confirma el archivo de revisión con la aceptación. Luego campaign land ID, que también elimina los árboles de trabajo de la misión, las ramas fusionadas y el espacio de compilación, y nombra lo que conservó.

Lotes de exploración

Para una lista que vale la pena cazar (las filas perdedoras de un benchmark fresco, los puntos calientes de un perfil, código escasamente probado, un backlog de pequeños errores), envía varios contribuyentes económicos a la vez, un objetivo cada uno, objetivos de una medición fresca en el main actual: references/assignments/exploration.md. Dimensiona el lote por sus objetivos y por lo que el líder puede revisar y fusionar, nunca por cuota inactiva.

Riesgo y revisión

Riesgo (gana la primera coincidencia)	Antes de construir	Antes de la fusión final
crítico: irreversible (congelar un formato o protocolo para un lanzamiento, migrar datos de usuarios, eliminar comportamiento visible para el usuario)	aprobación del propietario; una revisión design	la revisión de alto riesgo, más evidencia de aceptación que el revisor ejecutó él mismo
alto: formatos persistentes, protocolos de cable, durabilidad, concurrencia, superficies de seguridad, APIs públicas compartidas	una revisión design cuando una decisión es costosa de revertir	una revisión por el lente del riesgo dominante (durability, security o correctness)
normal: características y correcciones ordinarias	—	una revisión correctness, o --waive REASON para un cambio pequeño con evidencia sólida
bajo: docs, pruebas, herramientas, ediciones mecánicas, refactorizaciones que preservan comportamiento	—	verificaciones en verde; el líder lee el diff

• Un revisor por defecto, que lleva cada pregunta de riesgo que la misión plantea (el prompt nombra de tres a cinco). Un segundo solo para una pregunta que necesita experiencia separada o independencia.
• Una revisión está vinculada a lo que vio. Nombra el commit que revisó (Commit:), un veredicto y una tabla de hallazgos con un ID, Bloqueante (sí o no) y Tipo (defecto, brecha, nit) por fila. Un APRUEBA cubre el código de ese commit; los commits que tocan solo .campaign/ lo mantienen. Editar la revisión después de la aceptación invalida la aceptación.
• Las correcciones se confirman con trabajos, no con nuevas revisiones. Para cada hallazgo bloqueante, vuelve a ejecutar su sonda o la nueva prueba como un trabajo en el commit corregido, luego campaign accept ID LENS --confirm C1=TRABAJO --confirm C2=TRABAJO. Un trabajo confirma solo si pasó en el código aceptado en el repositorio de la misión; un defecto bloqueante necesita código modificado; la herramienta registra si la misma sonda falló en el commit revisado. Una corrección que cambia archivos que la revisión nunca vio vuelve al revisor (la revisión nombra el commit corregido y aprueba), a menos que --fix-scope REASON diga por qué no agrega ningún mecanismo (una prueba de regresión para un hallazgo).
• Dos rondas de corrección, luego detenerse. Una tercera significa que la misión o el diseño están mal: replanifica o pregunta al propietario. Los hallazgos no bloqueantes se convierten en una misión de seguimiento o se descartan con una razón.
• Un diseño se revisa una vez. Resuelve el comportamiento en disputa con un modelo ejecutable o una prueba, no con otra ronda de texto.
• Lo que una misión debe pasar cambia solo en el registro: campaign set ID ... --weaken REASON reduce su riesgo, elimina un lente, o elimina, cambia o difiere una verificación; el cambio se conserva en su historial, se muestra con campaign status ID, e invalida sus aceptaciones. La revisión que un riesgo necesita (una revisión de código por encima de bajo, una revisión de diseño para crítico) no se puede eliminar, y se rechaza una renuncia una vez que existe una revisión.
• Revisión del sistema en eventos, no en un calendario: cuando campaign check reporta dos misiones que cambian un archivo o un contrato, pide a un revisor (lente system) esa pregunta específica.
• Rendimiento: campaign status --reviews cuenta veredictos y defectos bloqueantes. Una revisión opcional (riesgo normal) que no encuentra nada sustancial en aproximadamente cinco misiones de un tipo se descarta para ese tipo; las revisiones altas y críticas nunca se descartan por rendimiento.

Evidencia

Cada criterio en un archivo de misión nombra la evidencia que necesita; la tabla de Evidencia del diario da una fila por criterio, y la fusión verifica cada fila en el código que se está fusionando:

Criterio	Su fila debe nombrar
- A1 ... (sin etiqueta)	un trabajo que pasó en ese código (él, o el mismo trabajo reejecutado)
- A2 [artifact] ...	una ruta confirmada en el repositorio de la misión
- A3 [decision] ...	un id en la tabla de Decisiones de PLAN.md
- A4 [manual] ...	quién verificó qué, a mano; mostrado como manual, nunca como prueba automatizada

La prueba es proporcional a la afirmación (references/review.md): las pruebas verifican valores, no conteos; una corrección tiene una prueba que falla sin ella; una afirmación tiene un mutante que una prueba mata; sanitizers en compilaciones separadas. Las afirmaciones de rendimiento siguen references/measurement.md: antes y después en commits nombrados, exclusive para números que deciden algo, magnitud honesta.

Trabajo de máquina

Nivel	Para	Aislamiento (quiet)
none	sondas pequeñas de un solo hilo	sin espera
light	compilaciones, suites de prueba, fuzzing	algunos a la vez, nice 19
strict	temporizaciones de humo, ejecuciones de comportamiento	núcleos propios en Linux; solo en macOS
exclusive	números que deciden algo	CPU y memoria sin contención; de lo contrario, no se ejecuta

• Los trabajos se ejecutan en el commit exacto que los envió, no en el último commit de la rama. Una prueba que falla o un error de compilación no afecta a otros trabajos.
• El líder usa --no-verify en los commits de los archivos del diario y de la misión; el gancho pre-commit del repositorio se aplica a los commits de trabajo real (código, pruebas, artefactos).
• campaign job submit --level none -- CMD para sondas rápidas; --light para compilaciones y suites de prueba; --strict para temporizaciones; --exclusive para números definitivos.

Referencias

Un directorio references/ en el repositorio de la campaña contiene:

Archivo	Propósito
references/harness.md	Modelos para cada proveedor de nivel (claude-code, openai-codex, aider, cursor, etc.)
references/prompts.md	Prompts del sistema para contribuyentes y revisores
references/assignments/	Métodos de asignación para cada tipo de trabajo
references/host.md	Configuración de máquina host, colas de mensajes, colas de trabajos
references/review.md	Prueba proporcional a la afirmación (cómo escribir buena evidencia)
references/measurement.md	Metodología de medición de rendimiento

Opciones de línea de comandos

Todas las órdenes de campaña comparten:

• --help para ayuda general
• --debug para salida detallada
• La mayoría de las órdenes aceptan --quiet para suprimir la salida normal
• --ci MODE para modo CI (github, gitlab, etc.)
• --machine para trabajo remoto (experimental)

Historial de versiones

• v1.0.0 (2025-01): Lanzamiento inicial
• v1.1.0 (2025-02): Lotes de exploración, mensajes
• v1.2.0 (2025-03): Trabajo entre repositorios, incrementos
• v1.3.0 (2025-04): Sistema de revisión, debilitamiento de verificación

Licencia

MIT