Saltar al contenido principal
EN ES
01:43 AM

EXPEDIENTE / INFRAESTRUCTURA DE AGENTES

Sistemas de agentes y memoria portable

Un flujo de trabajo verificable para delegar código sin delegar autoridad.

Los agentes de IA fallaban de formas que parecían éxito: una ruta de respaldo que nunca se activaba, un diff que pasaba las pruebas, una sesión quemando el modelo equivocado. Dejé de parchar prompts y construí un sistema de delegación con compuertas duras: un planificador que no puede escribir código, implementadores confinados a una lista de archivos permitidos, auditorías de solo lectura y un replay que puedo revisar línea por línea. Seis incidentes después, las reglas se escriben solas.

INFRAESTRUCTURA PERSONAL / DEMOSTRACIÓN TÉCNICA PÚBLICA

Abrir replay de ejecuciónRevisar evidencia

01 / EL PROBLEMA

Fallos que parecían éxito.

Tres incidentes documentados muestran el patrón que hizo necesario este flujo.

Cada fallo de delegación que sufrí parecía éxito desde afuera. Una corrida reportaba el agente READY mientras el uso del proveedor estaba en 0% — el cableado no demostraba nada sobre la inferencia. Otra dejó que los subagentes heredaran en silencio el modelo del planificador, quemando la cuota equivocada mientras el trabajo corría en otro lado. Una tercera regresó JSON inválido y reintentó de todas formas: el resultado se habría integrado como si estuviera revisado. Ninguna chocó. Todas se habrían enviado a producción. Mi sistema de entonces — prompts, confianza y una revisión de código al final — no distinguía una tarea completada de una convincente. El hueco no era la calidad del modelo; era la autoridad. Necesitaba una estructura donde un agente no pueda cruzar un límite, no una donde se le pide que no lo cruce.

02 / DECISIONES DE DISEÑO

Cinco decisiones que cargan el límite de autoridad.

La arquitectura se condensa en cinco decisiones con nombre. Cada rol de este flujo es consecuencia de una de ellas; el detalle completo de los 11 nodos vive en el apéndice.

  1. El planificador nunca escribe código

    Es de solo lectura sobre el repositorio: redacta briefs y planes, y se detiene cuando hace falta una decisión real de producto, seguridad o alcance.

  2. Los implementadores solo escriben dentro de una lista permitida

    Cada brief lista las rutas exactas que un implementador puede tocar. Cualquier cosa fuera de la lista es condición de paro, no una decisión a criterio.

  3. Las auditorías son compuertas duras de solo lectura

    El evaluador de agentes y el cazador de fallas silenciosas inspeccionan el diff sin acceso de escritura. Un veredicto de bloqueo detiene la entrega; no es una sugerencia.

  4. Los secretos nunca tocan el repo

    El repo solo declara nombres de variables; un envoltorio administrado por el equipo anfitrión inyecta las credenciales al proceso hijo. Creación, rotación y revocación siguen siendo humanas.

  5. La autoridad irreversible nunca se automatiza

    Cambios de alcance, despliegues a producción y acciones irreversibles requieren aprobación humana explícita registrada en el brief o en la bitácora de sesión.

01 / ARQUITECTURA

Un flujo donde la autoridad se nombra, no se asume.

Once nodos interactúan bajo reglas explícitas. El humano decide lo irreversible. Los agentes se ciñen a un brief y a una lista de archivos permitidos. Los componentes de memoria cargan datos, no autoridad.

  1. Humano / dueño del alcanceHumanoDecide cambios materiales de alcance, datos, costo, producción y acciones irreversibles. Autoriza corrección y reintento. Un veredicto técnico fallido no se convierte en éxito por intervención: la compuerta de fallas silenciosas sigue bloqueando la entrega hasta que la ruta queda corregida. Es la única autoridad para aprobar transiciones materiales cuando las compuertas técnicas pasan; puede autorizar una corrección o un nuevo intento, pero no puede convertir un veredicto fallido en éxito ni saltarse la compuerta de fallas silenciosas.

    Detalle completo de nodos en el apéndice

  2. Planificador plannerAgenteDe solo lectura sobre el repositorio. Escribe briefs y planes. No escribe código y no puede decidir nada que toque producto, seguridad o alcance.

    Implementador builderAgenteSolo escribe código dentro de una lista explícita de archivos permitidos. Reporta diff, lint, verificación de tipos y cualquier bloqueo. No elige archivos por su cuenta ni amplía el alcance.

    Detalle completo de nodos en el apéndice

  3. Evaluador de agentes agent_evaluatorAgenteDe solo lectura. Emite una tarjeta de evaluación contra la rúbrica acordada. No modifica archivos ni acepta trabajo por su cuenta. Puede emitir veredictos en texto sin escribir archivos.

    Cazador de fallas silenciosas silent_failure_hunterAgenteDe solo lectura. Bloquea la entrega ante cualquier falla silenciosa: catch vacíos, errores que se registran y se olvidan, rutas de respaldo peligrosas, errores no propagados.

    Detalle completo de nodos en el apéndice

  4. Creador de commits commit-creatorAgentePuede preparar cambios y crear commits solo tras aprobación humana explícita. Nunca hace push ni amend sobre historial ya publicado sin una nueva aprobación.

    Redactor de notas de versión release-noterAgenteProduce una vista previa a partir de un rango de commits y se detiene para aprobación. No publica, no crea tags ni modifica el CHANGELOG por su cuenta.

    Memorista del vault vault-memoristAgentePropone memorias de Engram y actualizaciones del vault. Puede guardar en Engram tras un OK explícito. Nunca edita el vault directamente. En el flujo general, un implementador puede aplicar un cambio al vault tras aprobación humana; en este proyecto esa edición queda fuera del alcance.

    Detalle completo de nodos en el apéndice

  5. EngramMemoriaSustrato de memoria compartida entre entornos de ejecución. No tiene autoridad humana por sí mismo. Se accede mediante llamadas autorizadas del entorno de ejecución; siguen aplicando las salvaguardas de señalamiento de conflictos y de juicio.

    knowledge-vaultMemoriaRepositorio versionado de decisiones, ADRs, documentación de agentes y manuales operativos. Los agentes lo leen; el memorista propone; un implementador aplica un diff aprobado y el creador de commits solo hace commit tras aprobación humana.

    Detalle completo de nodos en el apéndice

  6. Proveedor / capa de modeloProveedorSustrato de ejecución intercambiable. No otorga permisos por sí mismo; hereda los límites del rol que lo invoca. Cambiar de proveedor no esquiva una condición de paro.

    Detalle completo de nodos en el apéndice

02 / REPLAY DE EJECUCIÓN

Replay local determinista, no traza de producción.

El replay muestra cómo es un ciclo planificador-implementador: quién leyó qué, quién escribió qué, dónde se detuvo y qué evidencia produjo. Las cifras dentro del replay son sintéticas; la secuencia es fija.

SIMULACIÓN LOCAL DETERMINISTA / TELEMETRÍA SINTÉTICA

Replay listo. Evento 1 de 7.
Cinta de eventos1/7

Secuencia 1 · Fase Alcance

Humano fija alcance, no-objetivos y lista permitida; producción excluida

Rol: Humano / dueño del alcance Continuar

Entrada
{"scope":"Unidad de datos de replay y motor puro","nonGoals":["deploy","push","secret_write","production"],"allowlist":["src/data/agentSystemsReplay.ts","src/utils/agentReplay.ts","src/data/agentSystemsContent.ts","src/types/database.ts","src/env.d.ts","src/utils/collections.ts"],"production":false}
Salida
{"ack":"scope_fixed","production":false}
Evidencia
Alcance registrado localmente; lista permitida de 6 archivos preservada; tmp/ fuera del alcance; producción excluida explícitamente.
Pruebas
Este evento no ejecuta pruebas
Decisión
Aceptar alcance y pasar a la revisión previa
Motivo
El alcance está acotado, la lista permitida es explícita y la producción queda excluida por diseño.

Métricas

Métricas sintéticas. Determinista por diseño.
Duraciones por fase
  • Alcance 800 ms
  • Revisión previa 1200 ms
  • Despacho 950 ms
  • Implementación 1400 ms
  • Verificaciones 1500 ms
  • Evaluación 1350 ms
  • Aprobación 700 ms
Tokens simulados
1280
Archivos en la lista permitida
6
Pruebas ejecutadas
3
Compuertas aprobadas
3
Compuertas rechazadas
0
Errores detectados
0
Resultados de escenarios

Corrida exitosa

Un ciclo limpio de planificador e implementador: revisión previa, implementación, verificaciones simuladas, evaluación, escaneo del cazador y aprobación humana.

Pasó

passed: entrega aprobada localmente sin acciones de producción ni acciones que modifiquen git.

Esquema inválido

El implementador devuelve una carga útil que no cumple el esquema de cierre; el validador bloquea antes de aplicar cualquier cambio.

Bloqueado (esquema inválido)

invalid_schema: faltan claves requeridas de cierre en la carga útil; se requiere un brief corregido.

Falla silenciosa

El diff contiene una ruta de respaldo peligrosa; las verificaciones simuladas pasan, el cazador bloquea y se registra un brief de corrección sin aplicar ninguna corrección.

Bloqueado (falla silenciosa)

silent_failure: ruta de respaldo peligrosa detectada por el cazador; brief de corrección pendiente.

Compuerta humana

La operación material es denegada por el humano antes de que corra cualquier implementador; no se escribe nada, no se hace push ni se despliega.

Bloqueado (compuerta humana)

human_gate: operación material denegada por autorización humana.

04 / EVIDENCIA Y LÍMITES

Qué respalda y qué no respalda este expediente.

Evidencia documentada, el borde de lo que este expediente afirma y las compuertas de seguridad que lo sostienen, en un solo lugar.

Clave de evidencia:Sellos de evidencia usados en este expediente: Documentada = respaldada por un artefacto del repositorio auditable; Simulación = replay local determinista, no tráfico de producción; Decisión de diseño = una elección documentada, no un resultado ni una métrica.

Controles automatizados

  1. Lista permitida aplicada en tres capas

    El implementador solo escribe rutas listadas de forma explícita en el brief; los diffs se analizan como unified diff antes de aplicarse; los ejecutores experimentales previsualizan con git apply --check antes de cualquier escritura real. La entrada mal formada o fuera de alcance se rechaza.

  2. Auditorías de solo lectura

    El evaluador de agentes y el cazador de fallas silenciosas inspeccionan el diff sin acceso de escritura. Sus veredictos son compuertas, no sugerencias.

  3. Separación entre configuración, despacho e inferencia

    Cableado, despacho e inferencia sustantiva son capas distintas. El cableado por sí solo no es evidencia de que se usó el proveedor; el despacho por sí solo no es evidencia de que ocurrió la inferencia.

  4. Secretos fuera del repo

    El repo solo declara nombres de variables. Un envoltorio administrado por el equipo anfitrión obtiene la credencial del almacén seguro y la inyecta al proceso hijo; nunca se versiona ni se imprime. Creación, rotación y revocación siguen siendo acciones humanas.

  5. Compuertas humanas en puntos con nombre

    Cambios de alcance, despliegues a producción, acciones irreversibles y manejo de secretos requieren aprobación humana explícita registrada en el brief o en la bitácora de sesión.

Límite de autoridad humana

  1. Cambios de alcance

    Ningún agente amplía ni reduce el alcance del trabajo por su cuenta.

  2. Producción / despliegue

    Los despliegues a producción no los hacen agentes. Los humanos los aprueban y los ejecutan.

  3. Facturación y costo

    Decisiones de gasto, cambios de plan y movimientos de cuota no se delegan a agentes.

  4. Datos sensibles

    PII, credenciales y datos de clientes no se leen, escriben ni transmiten por flujos automatizados.

  5. Manejo de secretos

    Crear, rotar o revocar secretos es acción humana. Los agentes no tocan almacenes de secretos.

  6. Acciones destructivas o irreversibles

    Push, publicación, tags, sobrescritura forzada o limpieza irreversible de cachés requieren aprobación humana explícita.

  7. Sobrescritura forzada del respaldo

    Los respaldos nunca se sobrescriben a la fuerza durante una restauración. La restauración compara, elige la instantánea canónica, hace merge selectivo y verifica integridad antes de persistir.

  1. Documentada

    Definiciones de rol

    Matriz de roles, modelos, permisos y arquitectura portable y de runtime compartido.

    Fuente:knowledge-vault/docs/AGENTS-AND-MODELS.md

  2. Documentada

    Protocolo de despacho

    Separa cableado, despacho e inferencia sustantiva; documenta los incidentes de READY con uso en 0% y de proveedor incorrecto.

    Fuente:knowledge-vault/docs/CODEX-MINIMAX-DISPATCH.md

  3. Documentada

    Contrato del implementador

    Captura el contrato de la lista permitida y la respuesta ante invalid_json o invalid_schema bajo carga.

    Fuente:knowledge-vault/docs/CODEX-MINIMAX-BUILDER.md

  4. Documentada

    ADR-001-a: latest canónico con CAS remoto

    Registra la decisión de adoptar el esquema de latest canónico, sidecar remoto y CAS.

    Fuente:knowledge-vault/docs/ADR-001-knowledge-backup.md

  5. Documentada

    ADR-003: restauración con merge

    Define la selección del respaldo por contenido, merge selectivo y verificaciones de integridad; mtime es insuficiente como garantía.

    Fuente:knowledge-vault/docs/ADR-003-restore-with-merge.md

  6. Documentada

    Protocolo BACKUP-INTEGRITY

    Documenta que el sha256 se calcula sobre el dump consistente con WAL, con la corrección aplicada en shell y PowerShell; la verificación posterior a la subida quedaba pendiente al redactarse.

    Fuente:knowledge-vault/docs/BACKUP-INTEGRITY.md

  7. Documentada

    Entrega del Laboratorio de IA

    Documenta la respuesta con prompts y bloques acotados cuando la presión de contexto hizo que el modelo perdiera el hilo.

    Fuente:docs/AI-LAB-HANDOFF.md

Los documentos de abajo son artefactos del repositorio de soporte. El repositorio mismo no se enlaza desde esta página; la verificabilidad pública de este expediente descansa en el comportamiento determinista del replay de ejecución y en la transparencia de sus límites.

05 / LIMITACIONES

Lo que este expediente no afirma.

Estos límites no son salvedades por cortesía; son el borde de lo que el flujo puede afirmar responsablemente.

  1. La infraestructura es personal y experimental. No es un servicio gestionado y no tiene SLA.

  2. No es producción. Ni tráfico de producción, ni datos de producción, ni despliegues a producción pasan por este flujo.

  3. El replay de ejecución es 100% simulado. No llama APIs externas, no consume cuota de ningún proveedor y no produce cifras comparativas de rendimiento.

  4. El flujo depende de esquemas externos y de la disponibilidad de los proveedores. Una caída del proveedor o la deriva de esquemas pueden romper una sesión; el flujo no lo disimula.

  5. Cambios materiales — alcance, producción, acciones irreversibles, manejo de secretos — siempre requieren intervención humana.

06 / FALLOS Y REGLAS APRENDIDAS

Seis incidentes que dieron forma al flujo actual.

Cada incidente queda documentado con lo que pasó, qué riesgo corría, qué se hizo para corregirlo, qué evidencia lo respalda y qué regla dejó. Las cifras del reporte de auditoría aparecen como evidencia del incidente, no como claims comerciales.

  1. ready-usage-zero

    READY con uso en 0%

    Documentada
    Situación
    Una corrida reportó READY pero el medidor de uso del proveedor se quedó en 0%, algo que normalmente parecería un ida y vuelta exitoso.
    Riesgo
    Confundir cableado, despacho e inferencia sustantiva permitiría que una llamada de red exitosa ocultara que no ocurrió ninguna inferencia.
    Corrección
    Las capas se separaron de forma explícita. Se agregó una llamada verificable; el medidor pasó de 0% a 1%. El cableado por sí solo dejó de aceptarse como prueba de inferencia.
    Evidencia
    Una llamada observable movió el uso de 0% a 1%. Una sola respuesta no prueba que un proveedor o un modelo haya producido salida útil.
    Regla aprendida
    Separar cableado, despacho e inferencia sustantiva. Un estado verde no es resultado hasta que cada capa se observa por separado.

    knowledge-vault/docs/CODEX-MINIMAX-DISPATCH.md

  2. invalid-json-repeat

    invalid_json / invalid_schema repetidos bajo carga de implementación

    Documentada
    Situación
    Cargas de trabajo de implementación produjeron errores repetidos de invalid_json e invalid_schema durante la iteración.
    Riesgo
    Hacer reintento automático, subdividir el trabajo o subir max_tokens enmascararía la causa y gastaría presupuesto mientras degradaba la verificación.
    Corrección
    La unidad se detuvo en el primer error. No se aplicó reintento, subdivisión ni subida de max_tokens automáticos. El brief se reabrió con el fallo visible.
    Evidencia
    Salidas repetidas de invalid_json e invalid_schema en la bitácora de implementación. El paro fue manual, el error se preservó y la verificación no se saltó.
    Regla aprendida
    Detener la unidad al primer error de esquema o de parseo. Reintentar, subdividir o cambiar el límite de tokens no son la primera respuesta ante una salida mal formada.

    knowledge-vault/docs/CODEX-MINIMAX-DISPATCH.mdknowledge-vault/docs/CODEX-MINIMAX-BUILDER.md

  3. silent-fallback

    Ruta de respaldo silenciosa detectada por una auditoría de solo lectura

    Documentada
    Situación
    Un diff contenía una ruta de respaldo que podría haber enmascarado un fallo aguas arriba. El cazador de fallas silenciosas fue la compuerta que lo atrapó antes de la entrega.
    Riesgo
    Una ruta de respaldo silenciosa habría convertido un error real en un éxito aparente, erosionando la confianza en la salida de verificación y en la automatización posterior.
    Corrección
    El cazador devolvió un veredicto de bloqueo. La ruta de respaldo se expuso con su motivo o se eliminó. El diff solo se reevaluó después de que la ruta silenciosa quedó explícita.
    Evidencia
    El reporte de auditoría de despacho cubre 1,936 tokens, hashes iguales, 13 pruebas unitarias y quick_validate.py para la corrida del cazador de fallas silenciosas. Esas cifras se registran aquí como evidencia del incidente; no son un resultado comercial.
    Regla aprendida
    Las auditorías de solo lectura son compuertas. Si se detecta una ruta silenciosa, la entrega se detiene hasta que la ruta sea explícita.

    knowledge-vault/docs/CODEX-MINIMAX-DISPATCH.md

  4. context-overflow

    Contexto demasiado grande: el modelo perdió el hilo

    Documentada
    Situación
    Una sesión acumuló contexto suficiente para que el modelo perdiera el hilo y alucinara detalles que no estaban en el brief.
    Riesgo
    Una alucinación confiada podría haberse mergeado como si fuera un resultado verificado, contaminando el diff y el sustrato de memoria.
    Corrección
    El trabajo volvió a bloques acotados con checkpoints explícitos. El diagnóstico se hizo antes de cualquier reanudación, y se regresó con instrucciones y bloques acotados.
    Evidencia
    La entrega del Laboratorio de IA documenta que los prompts y bloques acotados volvieron a producir respuestas útiles tras la presión de contexto.
    Regla aprendida
    Bloques acotados primero. Cuando aparece presión de contexto, detenerse y diagnosticar antes de continuar.

    docs/AI-LAB-HANDOFF.md

  5. wrong-provider

    Proveedor / modelo incorrecto heredado por el agente

    Documentada
    Situación
    Agentes genéricos heredaron un proveedor y modelo previos (reportado como GPT-5.6-sol) y continuar con el agente no migró el proveedor.
    Riesgo
    Heredar un proveedor en silencio mezclaría experimentos; los resultados dejarían de corresponder con claridad al rol del que salieron.
    Corrección
    La sesión se cerró. Se creó un agente nuevo con el rol personalizado y el selector explícitos, y con el contrato de fork correspondiente. El prompt por sí solo no cambia el proveedor.
    Evidencia
    Incidente reportado por el usuario sin bitácoras de ejecución conservadas. Tratarlo como incidente reportado, no como traza; verificar la identidad del proveedor en cada corrida antes de sacar conclusiones.
    Regla aprendida
    La identidad del proveedor parte de la definición del agente. Cerrar y recrear con el agent_type y el contrato de fork correctos es mejor que continuar cuando el proveedor heredado es incorrecto.

    knowledge-vault/docs/CODEX-MINIMAX-DISPATCH.md

  6. backup-divergence

    Divergencia de respaldo: mtime más nuevo, contenido más viejo

    Documentada
    Situación
    Una restauración podía haber producido un archivo con mtime más nuevo pero contenido más viejo que su contraparte remota, y sobrescribir el remoto al sincronizar.
    Riesgo
    Tratar mtime como garantía de novedad habría destruido silenciosamente el contenido más reciente en favor de un respaldo obsoleto.
    Corrección
    Se adoptó y documentó el protocolo de restauración con merge: comparación de contenido, selección coherente del respaldo, diff y merge selectivos y verificación de integridad antes de cualquier escritura.
    Evidencia
    ADR-003 documenta el escenario real y el manual operativo. mtime queda explícitamente fuera de la prueba de canonicidad.
    Regla aprendida
    mtime no es garantía. Comparar contenido, elegir un respaldo coherente, hacer merge selectivo y verificar integridad antes de persistir.

    knowledge-vault/docs/ADR-003-restore-with-merge.md

07 / RESULTADO Y APRENDIZAJES

El resultado es un flujo, no una métrica de producción.

El resultado no es una métrica de producción — la sección de limitaciones lo dice sin rodeos. Es un flujo donde cada delegación carga un nombre, un brief, una lista permitida, una condición de paro y un puntero a su evidencia; y donde seis incidentes documentados se convirtieron en seis reglas vigentes. El replay de arriba es una simulación, y ese es justo el punto: las reglas son lo que sobrevivió.

Abrir replay de ejecuciónLeer la bitácora del Laboratorio de IA

08 / APÉNDICE

Arquitectura completa de referencia.

La topología completa de 11 nodos y los ocho contratos de rol, conservados sin cortes para quien necesite la profundidad.

Arquitectura completa (11 nodos + contratos de rol)
  1. Humano / dueño del alcanceHumanoDecide cambios materiales de alcance, datos, costo, producción y acciones irreversibles. Autoriza corrección y reintento. Un veredicto técnico fallido no se convierte en éxito por intervención: la compuerta de fallas silenciosas sigue bloqueando la entrega hasta que la ruta queda corregida. Es la única autoridad para aprobar transiciones materiales cuando las compuertas técnicas pasan; puede autorizar una corrección o un nuevo intento, pero no puede convertir un veredicto fallido en éxito ni saltarse la compuerta de fallas silenciosas.
    Lee
    • Estado del repositorio
    • Borradores de brief
    • Reportes de auditoría
    • Resultados de búsqueda en Engram
    Escribe
    • Cambios de alcance
    • Despliegues a producción
    • Manejo de secretos
    • Merges manuales
    Se detiene cuando
    • Nunca automatizado; pausar es, por definición, una acción humana. Un veredicto técnico fallido sigue siendo fallo hasta que la corrección es real.
  2. Planificador plannerAgenteDe solo lectura sobre el repositorio. Escribe briefs y planes. No escribe código y no puede decidir nada que toque producto, seguridad o alcance.
    Lee
    • Archivos del repositorio
    • Documentación
    • Memoria Engram
    • Briefs previos
    Escribe
    • Briefs y planes en ubicaciones aprobadas
    Se detiene cuando
    • Hace falta una decisión real de producto
    • El límite de seguridad es ambiguo
    • Se pide un cambio de alcance
    • La autoridad es ambigua o disputada
    Implementador builderAgenteSolo escribe código dentro de una lista explícita de archivos permitidos. Reporta diff, lint, verificación de tipos y cualquier bloqueo. No elige archivos por su cuenta ni amplía el alcance.
    Lee
    • Brief aprobado
    • Lista de archivos permitidos
    • Archivos del repo dentro de la lista permitida
    Escribe
    • Solo los archivos de la lista permitida
    Se detiene cuando
    • El brief es ambiguo o contradictorio
    • Hace falta un archivo fuera de la lista permitida
    • La verificación falla (lint, verificación de tipos, pruebas)
    • Aparece un bloqueo real
  3. Evaluador de agentes agent_evaluatorAgenteDe solo lectura. Emite una tarjeta de evaluación contra la rúbrica acordada. No modifica archivos ni acepta trabajo por su cuenta. Puede emitir veredictos en texto sin escribir archivos.
    Lee
    • Diff
    • Brief
    • Rúbrica
    • Salida de verificación
    Escribe
    • Tarjetas de evaluación y observaciones de auditoría
    Se detiene cuando
    • La evidencia es insuficiente para evaluar
    • El brief no permite evaluar
    • La verificación requiere ejecución que el evaluador no puede realizar
    • En cualquiera de esos casos el evaluador devuelve el control al planificador
    Cazador de fallas silenciosas silent_failure_hunterAgenteDe solo lectura. Bloquea la entrega ante cualquier falla silenciosa: catch vacíos, errores que se registran y se olvidan, rutas de respaldo peligrosas, errores no propagados.
    Lee
    • Diff
    • Bitácora de auditoría
    • Salida de verificación
    Escribe
    • Veredicto de bloqueo con punteros a evidencia
    Se detiene cuando
    • Se detecta una falla silenciosa; es una compuerta dura, no una advertencia.
  4. Creador de commits commit-creatorAgentePuede preparar cambios y crear commits solo tras aprobación humana explícita. Nunca hace push ni amend sobre historial ya publicado sin una nueva aprobación.
    Lee
    • Diff aprobado
    • Reglas de Conventional Commits
    Escribe
    • Commits locales dentro del árbol de trabajo
    Se detiene cuando
    • No hay aprobación humana registrada
    • Se pide push
    • Se pide amend sobre un commit ya publicado
    Redactor de notas de versión release-noterAgenteProduce una vista previa a partir de un rango de commits y se detiene para aprobación. No publica, no crea tags ni modifica el CHANGELOG por su cuenta.
    Lee
    • Rango de commits
    • Reglas de Conventional Commits
    Escribe
    • Vista previa de notas de versión en borrador
    Se detiene cuando
    • Hace falta aprobación humana antes de cualquier paso de publicación.
    Memorista del vault vault-memoristAgentePropone memorias de Engram y actualizaciones del vault. Puede guardar en Engram tras un OK explícito. Nunca edita el vault directamente. En el flujo general, un implementador puede aplicar un cambio al vault tras aprobación humana; en este proyecto esa edición queda fuera del alcance.
    Lee
    • Resumen de sesión
    • Aprendizajes candidatos
    • Claves de tema existentes
    Escribe
    • Observaciones en Engram tras OK explícito
    • Propuestas para el vault (pendientes)
    Se detiene cuando
    • No hay OK explícito
    • Una observación candidata entra en conflicto con una existente sin resolución
    • Haría falta editar el vault directamente
  5. EngramMemoriaSustrato de memoria compartida entre entornos de ejecución. No tiene autoridad humana por sí mismo. Se accede mediante llamadas autorizadas del entorno de ejecución; siguen aplicando las salvaguardas de señalamiento de conflictos y de juicio.
    Lee
    • Llamadas de guardado desde agentes autorizados
    • Llamadas de búsqueda desde agentes autorizados
    Escribe
    • Observaciones persistidas y veredictos de relación
    Se detiene cuando
    • Las escrituras en conflicto aparecen como judgment_required; la persistencia se pausa hasta que se juzgan.
    knowledge-vaultMemoriaRepositorio versionado de decisiones, ADRs, documentación de agentes y manuales operativos. Los agentes lo leen; el memorista propone; un implementador aplica un diff aprobado y el creador de commits solo hace commit tras aprobación humana.
    Lee
    • Diffs propuestos por el memorista
    • Briefs y reportes de los agentes
    Escribe
    • Diffs aplicados por el implementador tras aprobación
    • Commits creados por el creador de commits tras nueva aprobación
    Se detiene cuando
    • Se pide a un agente editar el vault sin el flujo de aprobación
    • No hay aprobación humana registrada
  6. Proveedor / capa de modeloProveedorSustrato de ejecución intercambiable. No otorga permisos por sí mismo; hereda los límites del rol que lo invoca. Cambiar de proveedor no esquiva una condición de paro.
    Lee
    • Lo que el rol que lo invoca tiene permitido leer
    Escribe
    • Lo que el rol que lo invoca tiene permitido escribir
    Se detiene cuando
    • El rol que lo invoca llega a su propia condición de paro; cambiar de proveedor no la esquiva.
Diagrama alternativo (texto plano)

Diagrama alternativo (texto plano)

Diagrama alternativo en texto: el humano decide alcance y aprobaciones; el planificador lee y planea; el implementador solo escribe dentro de la lista permitida; el evaluador de agentes y el cazador de fallas silenciosas leen el diff y emiten veredictos; el creador de commits y el redactor de notas de versión solo preparan commits o borradores; el memorista del vault solo propone y guarda en Engram tras un OK; Engram y el knowledge-vault guardan memoria; la capa de proveedor y modelo ejecuta bajo el rol que la invoca.

RolResponsabilidadHerramientasPermisosSalidaSe detiene cuando
Humano / dueño del alcanceDecide alcance, datos, costo, producción y acciones irreversibles.Repositorio, Engram, cuentas de infraestructura, herramientas de despliegue.Total; única autoridad para aprobar transiciones materiales cuando las compuertas técnicas pasan; puede autorizar una corrección o un nuevo intento, pero no puede convertir un veredicto fallido en éxito ni saltarse la compuerta de fallas silenciosas.Cambios de alcance, aprobaciones, despliegues, manejo de secretos, merges manuales.Nunca automatizado; pausar es, por definición, una acción humana. Un veredicto técnico fallido no se convierte en éxito por intervención: la corrección debe ocurrir y la compuerta de fallas silenciosas sigue bloqueando la entrega hasta entonces.
Planificador plannerLee repo, docs y memoria; redacta briefs y planes.Lectura de repo, lectura de docs, lectura de Engram, plantilla de brief.Solo lectura en el repo; escribe briefs y planes en ubicaciones aprobadas.Brief, plan, rúbrica, criterios de aceptación.Hace falta una decisión real de producto; el límite de seguridad es ambiguo; se pide un cambio de alcance; la autoridad es disputada.
Implementador builderEscribe código dentro de la lista permitida del brief y reporta la verificación.Escritura en el repo (lista permitida), lint, verificación de tipos, pruebas dirigidas.Limitado a los archivos listados en el brief; no edita memoria ni vault.Diff, salida de lint, salida de la verificación de tipos, salida de pruebas, reporte de bloqueos.Brief ambiguo; falta un archivo en la lista permitida; la verificación falla; aparece un bloqueo real.
Evaluador de agentes agent_evaluatorPuntúa el diff contra la rúbrica; emite un veredicto.Lectura de diff, rúbrica, salida de verificación.Solo lectura; no puede aceptar trabajo por su cuenta.Tarjeta de evaluación con criterios, evidencia y veredicto.Evidencia insuficiente; el brief no permite evaluar; la verificación requiere ejecución que el evaluador no puede realizar; en cualquiera de esos casos el evaluador devuelve el control al planificador.
Cazador de fallas silenciosas silent_failure_hunterBloquea la entrega ante fallas silenciosas: catch vacíos, errores que se registran y se olvidan, rutas de respaldo peligrosas, errores no propagados.Lectura de diff, bitácora de auditoría, salida de verificación.Solo lectura; una sola compuerta dura (bloqueo) sin excepciones.Veredicto de bloqueo con punteros a evidencia.Cualquier falla silenciosa detectada; el bloqueo no se negocia.
Creador de commits commit-creatorPrepara y crea commits locales con formato Conventional Commits.Git, reglas de Conventional Commits.Solo commits locales; nada de push ni amend sin nueva aprobación.Commit(s) local(es) listos para revisión.No hay aprobación humana registrada; piden push; piden amend de un commit ya publicado.
Redactor de notas de versión release-noterRedacta notas de versión a partir de un rango de commits.git log, analizador de Conventional Commits.Solo borrador; no crea tags ni publica.Vista previa de notas de versión en borrador.Hace falta aprobación humana antes de cualquier paso de publicación.
Memorista del vault vault-memoristFiltra qué vale la pena guardar; guarda en Engram solo tras un OK explícito.Lectura y escritura de Engram, filtro 2-de-3, sugerencia de claves de tema.Guarda en Engram tras un OK; propone cambios al vault; nunca edita el vault directamente. En el flujo general, un implementador puede aplicar un cambio al vault tras aprobación humana; en este proyecto el vault no se edita.Observaciones en Engram, propuestas para el vault pendientes de aprobación.No hay OK explícito; hay conflicto sin resolver con una observación previa; haría falta editar el vault directamente.