m1nga/loop-system-architect

Arquitecto de Sistemas de Bucle

Convierte una tarea repetitiva en un sistema de control observable que puede ejecutarse, demostrar su resultado, recuperarse tras una interrupción y mejorar sin reescribir su propio propósito.

Elige el modo

• Auditoría: inspecciona un flujo de trabajo existente e informa de las partes abiertas o faltantes. No edites a menos que te lo pidan.
• Diseño: produce el contrato, el esquema de estado, el gráfico de roles, las evaluaciones y el diseño en tiempo de ejecución.
• Operacionalización: implementa el controlador, los adaptadores, la persistencia, la evidencia y la ruta de ejecución con un solo comando.
• Evolución: analiza ejecuciones completadas, valida una mejora propuesta (bucle/conocimiento/habilidad) y promuévela o recházala.

Cuando el usuario pida "construir" o "ponerlo en funcionamiento", incluye Operacionalización. Un plan en Markdown por sí solo no es un bucle operativo.

Empieza desde la realidad actual

1. Lee las instrucciones del repositorio y los artefactos que el usuario ha colocado en el alcance.
2. Inspecciona las herramientas reales, los puntos de entrada, los archivos de estado, las pruebas, los programadores, las CLI de los agentes y el árbol de trabajo sucio.
3. Separa la entrada autorizada actual del material de referencia. No uses la memoria del modelo para llenar vacíos.
4. Clasifica el bucle:
   • Terminal: un objetivo con una línea de meta demostrable.
   • Recurrente: cada ejecución termina, mientras que el monitor/servicio continúa hasta que se retira.
5. Indica lo que existe, lo que falta y lo que solo se afirma antes de cambiar nada.

Para una auditoría completa, lee audit-rubric.md.

Requiere un bucle de control cerrado

Identifica y conecta todos estos elementos:

1. objetivo y propietario;
2. condición de finalización o condición de éxito por ejecución;
3. límite de fuente autorizada y procedencia;
4. desencadenante y verificación previa económica;
5. sensor y señal recopilada;
6. comparador, ventana y umbral/regla;
7. controlador y espacio de decisión finito;
8. actuador y la ruta que devuelve el nuevo resultado al sensor;
9. estado persistente, cursor, registro de eventos y almacén de evidencia;
10. responsabilidades del orquestador, ejecutor y verificador independiente;
11. descubrimiento abierto de capacidades/habilidades y creación de habilidades candidatas;
12. límites de autoridad y campos protegidos;
13. evaluaciones de aceptación y evidencia requerida;
14. reintentos, tiempos de espera, retroceso, clasificación de fallos y reversión;
15. idempotencia, desduplicación, bloqueo de concurrencia y punto de estrangulamiento de efectos secundarios;
16. presupuestos de tokens, costos, turnos y tiempo de pared;
17. observabilidad, alertas y un estado de éxito sin operación;
18. reemplazo directo de la verdad activa superada;
19. destilación de experiencia y promoción controlada;
20. condiciones de parada, pausa, eliminación y retiro.

La falta de retroalimentación sensor-actuador significa bucle abierto. La falta de estado persistente significa un prompt repetido. La falta de evidencia del verificador significa finalización autoafirmada. La falta de un controlador/desencadenante significa un procedimiento que los humanos deben operar.

Perfil mínimo

No todos los bucles necesitan los veinte elementos. Para un bucle de un solo operador y de calidad cron (un usuario, una máquina, bajo radio de explosión, sin efectos secundarios compartidos), un contrato es suficiente con ocho:

1. objetivo y propietario;
2. condición de éxito (finalización o por ejecución);
3. desencadenante y verificación previa económica;
4. actuador y su ruta de efectos secundarios;
5. estado persistente y cursor;
6. idempotencia/desduplicación en la ruta de efectos secundarios;
7. observabilidad: dónde ver el último resultado y la siguiente acción;
8. condición de retiro.

Declara las omisiones explícitamente en lugar de dejarlas en blanco: establece learning.enabled: false y capabilities.discovery: "none" con un campo reason. El linter acepta ambas. Consulta loop.contract.minimal-example.json para un contrato mínimo válido. Actualiza al contrato completo cuando el bucle adquiera efectos secundarios compartidos, un segundo operador, inquilinos externos o cualquier forma de automodificación.

Produce un paquete de bucle

Adapta los nombres al repositorio, pero mantén un contrato canónico legible por máquina y un registro de estado. Los paquetes de bucle, el estado y la evidencia residen en el proyecto del usuario, nunca dentro de este paquete de habilidad. El paquete predeterminado es:

loop/
├── LOOP-CONTRACT.md          contrato operativo legible por humanos
├── loop.contract.json        contrato canónico legible por máquina
├── RUN-STATE.json            ejecución actual, cursor, intentos, próxima acción de la máquina
├── events/                   eventos de ejecución de solo adición o un almacén de eventos equivalente
├── evidence/                 recibos legibles por el verificador
├── evals/                    comprobaciones de aceptación deterministas y semánticas
├── knowledge/                conocimiento promovido tipificado, no registros sin procesar
├── candidates/               lecciones no promovidas y cambios de habilidades
└── scripts/run-loop          controlador de un solo comando o equivalente nativo del proyecto

Usa loop-contract.md para el contrato de campos. Copia loop.contract.template.json, llena cada marcador de posición y luego ejecuta:

python3 scripts/loop_lint.py /path/to/loop.contract.json

Usa la copia dentro de esta habilidad cuando el proyecto no haya incluido el linter. Si no se puede escribir nada en el disco, genera el contrato y el controlador como texto copiable e indica qué falta colocar en el disco antes de que el bucle sea operativo.

Construye el controlador, no solo las instrucciones

El controlador debe hacer que una sola invocación avance el bucle sin pedirle al usuario que copie y pegue entre agentes:

1. adquirir un bloqueo de concurrencia y derivar una clave de idempotencia;
2. cargar y verificar el contrato y el estado;
3. verificar los hashes de fuentes congeladas o la autoridad de fuente actual;
4. ejecutar el desencadenante/verificación previa económica y registrar un éxito sin operación cuando no exista trabajo;
5. resolver las capacidades requeridas;
6. crear un paquete de contexto mínimo para el orquestador/ejecutor;
7. ejecutar en un espacio de trabajo aislado cuando sean posibles cambios;
8. capturar salidas, costos, llamadas a herramientas, diferencias y evidencia;
9. ejecutar un verificador independiente que no pueda certificar sus propias escrituras;
10. en caso de fallo, clasificar y enrutar una reparación acotada, reintento, reversión o parada;
11. en caso de éxito, promover atómicamente el resultado y actualizar el estado actual;
12. agregar un evento/recibo inmutable;
13. invocar la destilación solo cuando su desencadenante esté satisfecho;
14. liberar el bloqueo y exponer la siguiente acción ejecutable por la máquina.

Independencia mínima del verificador, por motor:

• Claude Code (o cualquier tiempo de ejecución con subagentes): ejecuta el verificador como un subagente de contexto nuevo que recibe solo el contrato, las comprobaciones de aceptación y las rutas de evidencia, no la conversación del ejecutor.
• Sin mecanismo de subagentes: ejecuta el verificador como un proceso separado o una invocación separada que relee la evidencia del disco y devuelve un veredicto contra las comprobaciones de aceptación.
• Ninguno disponible: el mismo contexto verificando su propio trabajo es autorrevisión (rendimiento, no verificación). Indícalo en la auditoría en lugar de etiquetarlo como verificador.

Prefiere código determinista para desencadenantes, transiciones de estado, comprobaciones de esquema, permisos, reintentos, hashes y promoción. Usa LLM para juicio, planificación, diagnóstico y contenido que no pueda decidirse mecánicamente.

Descubre o crea habilidades sin una lista blanca estática

Usa descubrimiento abierto con ejecución controlada:

1. Deriva un contrato de capacidad a partir de la tarea: entrada, salida, efectos secundarios, evidencia, riesgo.
2. Busca habilidades instaladas y capacidades del proyecto por metadatos y ajuste del contrato.
3. Inspecciona la procedencia y las dependencias; no importes la identidad incrustada del proyecto como verdad.
4. Aísla una habilidad candidata y ejecuta evaluaciones específicas de la capacidad.
5. Si ninguna encaja, crea una habilidad candidata de forma aislada con sus propios ejemplos y evaluaciones.
6. Promueve una versión solo después de que pase las comprobaciones de seguridad, privacidad, funcionalidad y regresión.
7. Registra localmente por defecto. La publicación externa sigue la política separada del entorno propietario.

El descubrimiento abierto no otorga autoridad abierta. Los mandatos, el alcance de los datos, la política de efectos secundarios y los permisos de tiempo de ejecución aún restringen cada habilidad.

Destila la experiencia en conocimiento utilizable

Nunca alimentes un registro cada vez más grande a cada agente. Mantén la evidencia sin procesar, los resúmenes episódicos, las lecciones candidatas, el conocimiento canónico, las habilidades procedimentales y las evaluaciones separados.

Ejecuta la ruta de promoción:

traza + resultado
→ episodio normalizado
→ lección candidata
→ desduplicar y verificar conflictos
→ reproducir contra ejecuciones anteriores y contraejemplos
→ sombra o canario
→ promover una versión
→ monitorear las siguientes ejecuciones
→ mantener o revertir

Activa la destilación ante fallos repetidos, trabajo manual repetido, desviación, regresión de costos, evidencia de resultados significativos o un tamaño de muestra configurado, no simplemente porque haya pasado el tiempo. Lee distillation.md antes de diseñar o cambiar la capa de aprendizaje. Si una habilidad de destilación dedicada (como experience-pack) está instalada, deja que ella posea el flujo de trabajo de destilación; esta habilidad diseña el bucle que la invoca.

El proceso de evolución puede mejorar SOP, desencadenantes, empaquetado de contexto, scripts, habilidades, recuperación y umbrales operativos dentro de la autoridad delegada. No puede reescribir silenciosamente el objetivo, el límite de la fuente, el límite de inquilino/privacidad, el modelo de autoridad o la evaluación que define el éxito.

Reemplaza la verdad activa limpiamente

Para cualquier actualización aceptada:

1. calcula el gráfico de impacto en contrato, esquema de estado, código, pruebas, documentación, vistas y habilidades;
2. declara REPLACES, REMOVES y KEEPS;
3. actualiza todos los dependientes;
4. elimina el texto y los valores obsoletos de la recuperación activa;
5. ejecuta escaneos de contradicciones/valores obsoletos;
6. ejecuta evaluaciones de rutas de éxito y fallo afectadas;
7. ejecuta una sonda de contexto cero que debe recuperar exactamente una respuesta actual;
8. promueve atómicamente; conserva las versiones anteriores solo en el control de versiones/historial de eventos, no en el contexto activo.

Calibra la autonomía

• Ejecuta automáticamente acciones reversibles y acotadas cuando la verificación determinista e independiente sea exitosa.
• Usa canario, sombra, verificación dual y reversión para acciones automatizadas de mayor riesgo.
• Detente para el usuario solo cuando falte autoridad, una decisión requerida cambie el objetivo o la acción sea materialmente irreversible y no esté ya autorizada.
• Nunca hagas que la aprobación humana rutinaria sea un actuador oculto en un bucle anunciado como autónomo.

Verifica la finalización

No llames operativo al bucle hasta que todo sea cierto:

• un comando o evento configurado puede avanzarlo sin transporte de prompts;
• la recuperación tras interrupción se reanuda desde el estado persistido sin rehacer el trabajo aceptado;
• los desencadenantes duplicados no pueden duplicar efectos secundarios;
• el fallo del verificador provoca una reparación acotada o una parada limpia;
• tanto las rutas de éxito como las de fallo cerrado tienen evidencia;
• una ejecución sin trabajo termina exitosamente y de forma económica;
• el estado actual, el último resultado, el costo, el fallo abierto y la siguiente acción son observables;
• se ha reproducido un candidato de evolución y se ha promovido o rechazado correctamente (exento bajo el perfil mínimo con learning.enabled: false);
• un agente de contexto cero puede explicar el contrato actual y la siguiente acción solo a partir de los archivos activos.

Informa por separado: qué está implementado, qué se ha ejercitado, qué permanece inactivo por falta de un sensor en vivo y qué aún requiere la autoridad del usuario.