414960701/harness-distiller

Harness Distiller (Destilador de Arneses de Agente)

Destila evidencia pública en arneses de agente (Agent Harness) implementables, verificables y actualizables. Trata los nombres de productos como recetas de comportamiento y capacidades, sin copiar marcas, prompts propietarios, material protegido o implementaciones internas no verificables.

Reglas obligatorias

1. Distingue entre code, official-doc, protocol, behavior e inference; no escribas inferencias de productos cerrados como si fueran hechos del código fuente.
2. Los cuatro niveles de madurez comparten el mismo protocolo, modelo de estado y límites de módulo; las actualizaciones solo añaden capacidades y optimizaciones, no generan cuatro conjuntos de ingeniería incompatibles.
3. Primero, implementa un corte vertical completo: modelo → bucle de agente → una herramienta de lectura → permisos → ejecución → eventos → estado → interfaz.
4. Mantén el runtime headless; CLI, TUI, IDE, escritorio y web interactúan solo a través de un protocolo versionado de comandos/eventos.
5. Separa la política de aprobación (approval policy) de la aplicación del sandbox; la aprobación del usuario no reemplaza los límites obligatorios del SO, contenedor, ruta de archivos o red.
6. Cada elemento "implementado" debe tener una ubicación de código; cada elemento "verificado" debe tener pruebas ejecutables o evidencia de comportamiento reproducible.
7. No consideres que "el modelo puede llamar a shell" es un "Harness completo". Debes implementar cancelación, fallo, recuperación, persistencia, permisos y reconstrucción del estado de la interfaz.

Lectura bajo demanda

• Para seleccionar un producto y comprobar la integridad del directorio, lee references/catalog.md.
• Para seleccionar un nivel o actualizar entre niveles, lee references/levels.md.
• Para decidir cuándo una capacidad puede marcarse como verificada (verified), lee references/capabilities.md.
• Para juzgar la fiabilidad de la evidencia, lee references/evidence.md y references/source-registry.md.
• Para entender los límites compartidos, lee references/architecture.md.
• Antes de comenzar a escribir código, DEBES leer references/implementation/index.md y luego cargar las especificaciones de implementación según su ruta.
• Para seleccionar capacidades compartidas, lee references/knowledge/index.md; carga solo los módulos de conocimiento seleccionados por el blueprint.
• Para clonar un producto, lee references/products/<product>/index.md y carga los 13 dosieres de ese producto en el orden especificado por el índice.
• Para crear un nuevo proyecto, lee references/workflows/build.md.
• Para actualizar un proyecto existente, lee references/workflows/upgrade.md.
• Para validar un proyecto, lee references/workflows/validate.md.

Analizar la solicitud

A partir de la solicitud del usuario y del repositorio de destino, analiza:

• recipe: un producto, hybrid o custom;
• level: runnable, usable, productive o polished;
• surfaces: cli, tui, ide, desktop, web, sdk, headless;
• execution: local, container, remote o combinaciones;
• stack: prioriza mantener el stack del repositorio de destino; para proyectos nuevos, elige según la superficie del producto y los requisitos de seguridad;
• providers: proveedores de modelos, modelos locales y requisitos de degradación de capacidades;
• security: modelo de amenazas personal, de equipo o empresarial;
• distribution: código fuente, paquete, extensión, aplicación de escritorio o servicio alojado.

Cuando el usuario solo diga "haz un producto como Codex/Claude Code/QoderWork", selecciona por defecto la receta correspondiente, usable, la superficie principal del producto más headless, y escribe las suposiciones en el registro de decisiones.

Para otras opciones no especificadas, usa los valores predeterminados: execution=local, security=personal, distribution=source; para Codex-like, por defecto Rust + headless/TUI; para Claude-Code-like, por defecto TypeScript + headless/CLI; para QoderWork-like, por defecto TypeScript + Tauri/Rust executor + headless/Desktop; para Aider-like, por defecto Python + headless/CLI; para OpenCode, por defecto TypeScript/Bun + headless/TUI; para OpenHands, por defecto Python + TypeScript/React + headless/Web/SDK; para AgentScope, LangGraph y Deep Agents, por defecto Python + headless/SDK. Cuando no se especifique el proveedor, implementa primero un contrato neutral para el proveedor, un fixture de script determinista y una interfaz adaptadora compatible con OpenAI; no vincules servicios de pago por iniciativa propia; antes de la integración real, solicita al usuario la configuración del proveedor.

Flujo de generación

1. Verifica el repositorio, el stack tecnológico, las instrucciones existentes, los cambios sucios (dirty changes) y el entorno de ejecución disponible.
2. En references/catalog.md confirma que el producto esté en nivel de implementación; no generes una clonación de producto para recetas planificadas pero que no tengan completados los 13 dosieres; primero completa los dosieres o cambia explícitamente a hybrid/custom. Luego ejecuta scripts/new_blueprint.py para crear .harness-distill/blueprint.yaml.
3. Lee index.md, product-contract.md, recipe.md y acceptance-tests.md del producto.
4. Según la receta, carga las especificaciones de implementación y los documentos de conocimiento compartido, estableciendo el cierre de dependencias de capacidades.
5. Escribe .harness-distill/evidence.md, registrando afirmaciones, URL, fecha, versión/commit, tipo de evidencia y nivel de confianza.
6. Escribe .harness-distill/decisions.md, registrando decisiones arquitectónicas, inferencias de código cerrado, no-objetivos, riesgos y puntos de retroceso.
7. Implementa primero el protocolo, el esqueleto de estado y un corte vertical ejecutable; guarda y reproduce su traza de eventos.
8. Completa las capacidades en el orden: schema → protocol → runtime → executor/policy → surface → migration.
9. Agrega simultáneamente pruebas de contrato, escenario, seguridad, recuperación, migración y pruebas de caja negra del producto.
10. Ejecuta scripts/validate_blueprint.py, la verificación del repositorio de destino y acceptance-tests.md del producto.
11. Solo marca como verified aquellas capacidades que tengan ubicación de implementación y evidencia de prueba.

Contrato mínimo de artefactos

El proyecto de destino DEBE contener límites equivalentes:

.harness-distill/
  blueprint.yaml       # selección, nivel, capacidades, estado y versión del contrato
  evidence.md          # evidencia pública y límites de inferencia
  decisions.md         # decisiones arquitectónicas, no-objetivos, riesgos y migración
src/
  protocol/            # negociación de command/event/error/schema/capability
  runtime/             # máquina de estados de turn, cancelación, reintento, presupuesto, steering
  model/               # adaptador de proveedor y negociación de capacidades
  context/             # instrucciones, recuperación, memoria, presupuesto, compresión, caché
  tools/               # schema, registro, enrutador, ciclo de vida, artefacto
  policy/              # allow/deny/ask/amend y alcance de aprobación
  execution/           # workspace, archivos, shell, parches, red, sandbox
  state/               # thread/turn/item/event/checkpoint/migration
  surfaces/            # adaptadores CLI/TUI/IDE/Desktop/Web
tests/
  contracts/           # pruebas de contrato de protocolo, proveedor, herramienta y almacenamiento
  scenarios/           # bucles cerrados de tareas reales
  security/            # desbordamiento, inyección, secretos, red y escape
  recovery/            # caídas, entrega duplicada, desconexión y migración

Se permite renombrar según las convenciones del lenguaje, pero no se pueden fusionar los límites entre política y ejecución, estado de dominio y proyección de UI, ni historial del modelo y hechos persistentes.

Compuerta de integridad

Solo se considera un Harness completo del nivel seleccionado cuando se cumplen TODAS las condiciones siguientes:

• El blueprint, el contrato del producto y las ubicaciones de implementación son coherentes;
• La traza de thread/turn/item/event del nivel runnable es persistible y reproducible; a partir de usable, admite paginación y recuperación tras reinicio del proceso; polished además requiere migración entre versiones;
• El emparejamiento tool call/result es atómico, con semántica clara para cancelación, tiempo de espera y resultados tardíos;
• Después de la compresión de contexto seleccionada, no se rompe la atomicidad de las llamadas a herramientas, la jerarquía de instrucciones ni el alcance de auditoría;
• Las acciones restringidas se deciden primero por la política y luego se imponen mediante límites de ejecución reales;
• La UI se puede reconstruir mediante snapshot + evento, sin depender de objetos en memoria del runtime;
• La recuperación tras caídas a partir de usable no repite efectos secundarios irreversibles;
• Las pruebas del escenario de nivel actual en acceptance-tests.md del producto pasan;
• Las notas de entrega enumeran comportamientos no soportados, lagunas de evidencia y rutas de actualización directas.

Actualización entre niveles

Al actualizar directamente desde cualquier nivel inferior a un nivel superior:

1. Verifica el blueprint, el protocolo y el esquema de base de datos actuales;
2. Calcula el delta de capacidades y expande las dependencias intermedias;
3. Primero migra el esquema, luego amplía el protocolo, runtime, ejecutor e interfaz;
4. Mantén al menos un límite de compatibilidad de migración para la configuración y los eventos antiguos;
5. Para acciones externas irreversibles, establece puntos de control, claves de idempotencia o confirmación manual;
6. Ejecuta todas las regresiones del nivel inferior y las pruebas de aceptación del nuevo nivel;
7. Solo después de que las pruebas pasen, actualiza el estado de las capacidades.