# Protocolo científico: deriva de agentes en repositorios en crecimiento ## Estado - Estado: protocolo experimental inicial - Producto relacionado: Objective Guard - Propósito: someter a falsación la tesis que motiva el producto - Regla metodológica: el experimento debe poder concluir que la tesis es incorrecta o insuficiente ## 1. Observación inicial En proyectos pequeños, los agentes de programación suelen completar tareas con pocos desvíos. Durante una etapa intermedia de crecimiento, pueden explorar caminos innecesarios, expandir el alcance o intentar reescrituras. Cuando el mismo software adquiere límites modulares claros, contratos y tests extensivos, el desempeño del agente puede mejorar nuevamente, aun cuando el repositorio sea mayor. Esta observación no constituye evidencia suficiente. Puede estar confundida por diferencias entre tareas, modelos, prompts, lenguajes, calidad del código o experiencia del usuario. ## 2. Tesis a investigar ### Tesis del fenómeno El desempeño de agentes de código no depende principalmente del tamaño bruto del repositorio. Depende de la relación entre complejidad efectiva y estructura verificable: \[ Q = \frac{C_e}{L + O + K} \] Donde: - \(C_e\): complejidad efectiva relevante para la tarea; - \(L\): localidad producida por modularidad y bajo acoplamiento; - \(O\): observabilidad aportada por tests y feedback ejecutable; - \(K\): contratos explícitos, tipos, schemas e invariantes. Cuando \(Q\) aumenta, debería aumentar la probabilidad de deriva. El crecimiento estructural posterior puede reducir \(Q\), aunque aumente el número total de líneas o archivos. ### Tesis del instrumento La deriva puede detectarse anticipadamente mediante señales cuantitativas de expansión, distancia arquitectónica, incertidumbre y evidencia: \[ R_t = f(X_t, U_t, E_t) \] Donde: - \(X_t\): expansión de la superficie del cambio hasta el paso \(t\); - \(U_t\): incertidumbre observable; - \(E_t\): evidencia acumulada a favor de la solución. El predictor debe anticipar fallos mejor que baselines simples como líneas modificadas, cantidad de archivos o duración de la tarea. ## 3. Hipótesis falsables ### H1: tamaño bruto Controlando por tipo y dificultad de tarea, el tamaño bruto del repositorio tendrá menor poder explicativo sobre el éxito que la complejidad efectiva y la localidad. Se rechaza H1 si líneas, archivos o tokens del repositorio explican el desempeño igual o mejor que las métricas estructurales fuera de la muestra. ### H2: valle de desempeño Para evoluciones comparables de un mismo sistema, el desempeño mostrará una curva no monótona: alto en una versión pequeña, menor en una versión de crecimiento orgánico y mayor nuevamente en una versión modularizada y observable. Se rechaza H2 si la caída intermedia no se replica o si desaparece al controlar dificultad y familiaridad. ### H3: superficie anómala Las trayectorias que terminan en una solución incorrecta presentarán, antes de finalizar, mayor superficie normalizada, distancia al objetivo y dispersión arquitectónica que las trayectorias correctas de la misma clase. Se rechaza H3 si estas señales no discriminan fallos fuera de la muestra mejor que el azar o que un baseline de tamaño del diff. ### H4: evidencia relativa La relación entre evidencia acumulada y superficie modificada discriminará mejor las trayectorias problemáticas que la superficie aislada: \[ J_t = \frac{E_t + \epsilon}{S_t + \epsilon} \] Se rechaza H4 si agregar \(J_t\) no mejora significativamente calibración, discriminación o anticipación. ### H5: intervención temprana Una alerta estadística temprana reducirá superficie innecesaria, tokens y tiempo hasta una solución correcta sin disminuir la tasa de resolución. Se rechaza H5 si la intervención no mejora costo o calidad, o si sus falsos positivos reducen el éxito neto. ## 4. Hipótesis rivales El protocolo debe intentar distinguir la tesis de estas explicaciones alternativas: 1. **Sólo tamaño:** el contexto adicional es la causa y la modularidad aparente no importa. 2. **Sólo dificultad:** los proyectos medianos contienen tareas intrínsecamente más difíciles. 3. **Sólo tests:** toda recuperación proviene del feedback, no de la estructura. 4. **Sólo familiaridad:** los modelos reconocen patrones frecuentes de repositorios maduros. 5. **Calidad general:** código mejor escrito explica todo; modularidad no aporta de forma independiente. 6. **Interacción humana:** el usuario formula mejores prompts cuando el proyecto madura. 7. **Dependencia del agente:** el fenómeno ocurre en un único modelo o harness. 8. **Sesgo de supervivencia:** sólo observamos repositorios que sobrevivieron hasta adquirir buena arquitectura. ## 5. Definiciones operacionales ### 5.1 Unidad experimental Una unidad es una ejecución independiente de: ```text agente × modelo × versión de repositorio × tarea × semilla ``` La unidad de análisis no debe ser únicamente el patch final. Se registra la trayectoria completa de acciones. ### 5.2 Éxito Una ejecución es correcta cuando: - satisface tests ocultos definidos antes de ejecutar el agente; - no viola contratos ni invariantes ocultos; - cumple el criterio funcional de la tarea; - no introduce cambios fuera de alcance considerados inválidos por evaluación humana ciega; - deja el repositorio construible. Pasar tests visibles no es una definición suficiente de éxito. ### 5.3 Deriva Existe deriva cuando la trayectoria se aleja del conjunto mínimo de cambios justificables por la tarea y no obtiene evidencia proporcional. Se etiqueta mediante una rúbrica previa: - `none`: trayectoria enfocada; - `recoverable`: exploración innecesaria revertida sin afectar el resultado; - `material`: expansión que incrementa costo o riesgo; - `terminal`: la expansión causa fracaso, regresión o abandono. Dos evaluadores ciegos etiquetan una muestra. Se informa acuerdo mediante Cohen's kappa o Krippendorff's alpha. Los desacuerdos no se eliminan: se adjudican y se reportan. ### 5.4 Reescritura Se considera intento de reescritura cuando ocurre al menos uno de estos eventos: - reemplazo de un componente completo sin que el objetivo lo requiera; - traslado o recreación de una proporción predefinida de símbolos del módulo; - crecimiento abrupto del radio arquitectónico; - eliminación y recreación semánticamente equivalente de una porción sustancial; - declaración explícita de estrategia de reescritura en la trayectoria. Los umbrales se fijan durante el piloto y se congelan antes de evaluar. ## 6. Variables independientes ### Tamaño bruto - líneas de código; - archivos; - símbolos; - tokens estimados; - cantidad de paquetes. ### Complejidad efectiva de tarea - cantidad de símbolos necesarios para resolverla; - cantidad de módulos relevantes; - longitud mínima del camino de dependencias; - cantidad de invariantes aplicables; - entropía de posibles localizaciones iniciales. ### Localidad estructural - acoplamiento aferente y eferente; - modularidad del grafo; - cohesión interna; - proporción de dependencias que atraviesan fronteras; - tamaño del cierre transitivo relevante; - estabilidad de APIs internas y públicas. ### Observabilidad - cobertura relevante, no cobertura global; - mutation score; - tiempo hasta el primer feedback; - proporción de criterios representados por tests; - especificidad diagnóstica de los errores; - existencia de tests focalizados. ### Contratos - densidad de tipos y schemas en fronteras; - cantidad de invariantes ejecutables; - porcentaje de APIs públicas versionadas o verificadas; - presencia de reglas arquitectónicas automáticas. ## 7. Variables dependientes ### Calidad - resolución correcta binaria; - proporción de tests ocultos aprobados; - regresiones introducidas; - severidad de violaciones contractuales; - evaluación funcional ciega. ### Eficiencia - tokens de entrada y salida; - tiempo de pared; - cantidad de acciones y herramientas; - cantidad de archivos leídos; - cantidad de patches descartados; - costo monetario normalizado. ### Trayectoria - tiempo hasta la primera edición correcta; - tiempo hasta la primera deriva; - máxima superficie alcanzada; - superficie final; - área bajo la curva de superficie; - cantidad de cambios de hipótesis; - distancia arquitectónica acumulada; - tiempo entre introducir y detectar un defecto. ## 8. Métricas de superficie El repositorio se representa como un grafo dirigido y tipado \(G=(V,E)\). Los nodos representan módulos, archivos y símbolos; las aristas representan imports, llamadas, herencia, eventos, datos compartidos y dependencias de build. ### Superficie vectorial Para cada paso \(t\): \[ \mathbf{s}_t = [F_t,L_t,Y_t,M_t,P_t,D_t,H_t,C_t] \] Donde: - \(F_t\): archivos modificados; - \(L_t\): churn de líneas; - \(Y_t\): símbolos modificados; - \(M_t\): módulos afectados; - \(P_t\): fronteras públicas modificadas; - \(D_t\): distancia al conjunto objetivo; - \(H_t\): entropía de distribución entre módulos; - \(C_t\): centralidad de los nodos modificados. ### Distancia al objetivo Sea \(O\) el conjunto de nodos relevantes establecido mediante ground truth: \[ D_t = \frac{\sum_{v \in C_t} w(v)\min_{o\in O}d_G(v,o)} {\sum_{v \in C_t}w(v)} \] Se reportan media ponderada, mediana y percentil 95. ### Dispersión Si \(p_i\) es la proporción del cambio en el módulo \(i\): \[ H_t=-\sum_i p_i\log p_i \] ### Área bajo la superficie Para capturar trabajo transitorio que no aparece en el diff final: \[ AUS = \sum_{t=1}^{T} S_t\Delta t \] Esto evita considerar equivalentes una trayectoria directa y otra que reescribió medio sistema para luego revertirlo. ## 9. Medición de evidencia La evidencia no se mide por cantidad de texto explicativo. Sólo cuentan resultados reproducibles. Para cada criterio \(a_j\): \[ e_j \in \{0, 0.25, 0.5, 0.75, 1\} \] Una rúbrica inicial puede asignar: - `0`: sin evidencia; - `0.25`: chequeo indirecto o incompleto; - `0.5`: test visible relacionado; - `0.75`: test directo más contrato relevante; - `1`: evidencia directa, independiente y con caso negativo o mutation testing. La evidencia total ponderada es: \[ E_t = \sum_j q_j e_{j,t} \] Los pesos \(q_j\) se fijan antes del experimento según criticidad del criterio. Debe realizarse un análisis de sensibilidad con pesos uniformes para comprobar que la conclusión no depende de ponderaciones convenientes. ## 10. Diseño experimental ### Experimento A: curva de madurez controlada Se construyen varios sistemas equivalentes en tres estados: 1. `small`: funcionalidad reducida y abarcable; 2. `organic`: funcionalidad completa, límites débiles y tests parciales; 3. `modular`: misma funcionalidad que `organic`, con límites explícitos, contratos y observabilidad. Las versiones `organic` y `modular` deben ofrecer el mismo comportamiento externo y tareas funcionalmente equivalentes. La diferencia intencional es la estructura y la observabilidad. Para separar sus efectos se utiliza un diseño factorial: ```text estructura débil × tests débiles estructura fuerte × tests débiles estructura débil × tests fuertes estructura fuerte × tests fuertes ``` Esto permite estimar efectos principales e interacción. ### Experimento B: repositorios reales longitudinales Se seleccionan repositorios con historia suficiente y se reconstruyen snapshots previos a: - crecimiento significativo; - modularización; - aumento de tests o contratos. Se crean tareas contrafactuales comparables o se reutilizan issues cuya solución pueda portarse entre snapshots. Este experimento aporta validez externa, pero no reemplaza el control del Experimento A. ### Experimento C: detección temprana Con trayectorias recolectadas en A y B: 1. se entrena o calibra el detector en un subconjunto de repositorios; 2. se congela el modelo; 3. se evalúa en repositorios y tareas no vistos; 4. se mide en qué paso podía anticiparse el fracaso. ### Experimento D: intervención Ensayo aleatorizado con tres condiciones: - control: agente sin alertas; - placebo: checkpoints con mensajes neutros y misma interrupción; - guard: alertas estadísticas accionables. El placebo permite separar el beneficio de “hacer una pausa” del beneficio específico de la señal. ## 11. Muestreo y asignación - Incluir al menos tres familias de agentes o modelos. - Ejecutar múltiples semillas por combinación. - Balancear bugfix, feature, refactor e improvement. - Estratificar por dificultad medida independientemente. - Aleatorizar el orden de las condiciones. - Impedir que una misma conversación vea varias variantes de la misma tarea. - Separar repositorios de calibración y evaluación para evitar contaminación. El tamaño muestral definitivo se determina con un piloto y análisis de potencia. No se fija a partir de un efecto observado en la evaluación final. Como punto de partida operativo, el piloto puede usar 20 tareas, 3 estados y 3 repeticiones. Su propósito es estimar varianza, fallos de instrumentación y tamaño de efecto, no confirmar la tesis. ## 12. Baselines El predictor completo debe compararse contra: 1. azar; 2. líneas modificadas; 3. archivos modificados; 4. tokens consumidos; 5. tiempo transcurrido; 6. cantidad de tests fallidos; 7. detector sin información del objetivo; 8. detector sin grafo arquitectónico; 9. detector sin evidencia acumulada. Las ablaciones 7–9 permiten comprobar qué componentes aportan valor real. ## 13. Plan estadístico ### Desempeño del agente Usar un modelo jerárquico logístico: \[ \operatorname{logit}P(Y=1) = \beta_0 + \beta_1 Size + \beta_2 Complexity + \beta_3 Locality + \beta_4 Observability + \beta_5 Contracts + \beta_6 Locality\times Observability + u_{repo}+u_{task}+u_{model} \] Los efectos aleatorios controlan diferencias entre repositorios, tareas y modelos. Para evaluar el valle se compara un modelo lineal contra uno con término cuadrático o spline. La forma no monótona debe mejorar predicción fuera de muestra y replicarse entre repositorios; no basta con que el término cuadrático sea significativo. ### Tiempo hasta deriva o corrección Usar análisis de supervivencia con riesgos competitivos: - evento 1: deriva material; - evento 2: solución correcta; - censura: límite de tiempo o tokens. ### Detector Reportar: - AUROC, pero no usarla sola; - AUPRC, especialmente si la deriva es infrecuente; - Brier score; - calibration curve y expected calibration error; - recall a una tasa fija de falsas alertas; - anticipación mediana en acciones, tokens y segundos; - utilidad neta según costo de alertar y costo de no detectar. ### Rangos conformales La no conformidad de una trayectoria puede definirse como: \[ A_t = g(\mathbf{s}_t, U_t, E_t) \] El p-value conformal es: \[ p_t = \frac{1+\#\{i:A_i\ge A_t\}}{n+1} \] La interpretación autorizada es: “esta trayectoria es igual o más extrema que aproximadamente X % de las trayectorias comparables”. No debe interpretarse como probabilidad directa de que el código sea incorrecto. ### Correcciones y reporte - Definir una métrica primaria y un horizonte primario antes de evaluar. - Aplicar corrección por comparaciones múltiples en análisis secundarios. - Reportar intervalos de confianza o credibilidad, no sólo p-values. - Publicar tamaños de efecto absolutos y relativos. - Mantener análisis exploratorios claramente separados de confirmatorios. ## 14. Prevención de fuga de información - Tests ocultos no accesibles al agente. - Soluciones humanas removidas del checkout y del contexto. - Tareas posteriores al cutoff cuando sea relevante para el modelo. - Repositorios completos separados entre calibración y test. - Prompts, límites de herramientas y presupuesto idénticos entre condiciones. - Sin ajuste de umbrales después de observar el conjunto final. ## 15. Instrumentación mínima Cada ejecución debe registrar eventos append-only: ```json { "run_id": "run_001", "step": 17, "timestamp": "...", "action": "apply_patch", "files_read": ["..."], "files_changed": ["..."], "diff_hash": "...", "graph_surface": {}, "checks": [], "tokens": {}, "goal_contract_hash": "..." } ``` Debe conservarse cada estado intermedio o un patch reproducible. Medir sólo el estado final destruiría evidencia central sobre la deriva. ## 16. Criterios de decisión La tesis del fenómeno recibe apoyo inicial si: - estructura, observabilidad y contratos predicen éxito fuera de muestra mejor que tamaño bruto; - aparece una caída intermedia replicable; - el diseño factorial muestra recuperación atribuible a estructura, tests o su interacción; - el efecto aparece en más de una familia de agentes. La tesis del instrumento recibe apoyo inicial si: - supera baselines simples en AUPRC y calibración; - detecta una fracción útil de derivas antes de que se vuelvan terminales; - mantiene una tasa predefinida de falsas alertas; - la intervención reduce costo sin reducir resolución. Debe reformularse o rechazarse si: - el tamaño bruto explica todo el efecto; - la recuperación proviene exclusivamente de tests; - las métricas de superficie no generalizan a repositorios nuevos; - las alertas sólo funcionan retrospectivamente; - la intervención distrae al agente y empeora el resultado neto. ## 17. Prerregistro Antes del conjunto confirmatorio se debe congelar y versionar: - hipótesis primarias; - dataset y exclusiones; - definición de éxito y deriva; - features y fórmulas; - modelo estadístico; - umbrales de alerta; - métrica primaria; - reglas de detención; - tratamiento de ejecuciones fallidas; - seeds y presupuesto por agente. Cualquier cambio posterior se declara como exploratorio. ## 18. Primer experimento ejecutable ### Pregunta ¿La estructura modular y la observabilidad recuperan el desempeño de un agente en un sistema de igual funcionalidad y tamaño aproximado? ### Construcción Crear una aplicación con seis módulos funcionales y preparar cuatro variantes factoriales: ```text A: límites débiles / tests débiles B: límites fuertes / tests débiles C: límites débiles / tests fuertes D: límites fuertes / tests fuertes ``` Preparar 12 tareas equivalentes: - 4 bugfixes; - 3 features; - 3 refactors; - 2 mejoras cuantificables. Cada tarea tendrá tests ocultos, conjunto objetivo de símbolos y patch humano mínimo usado sólo para medir distancia, no como única solución válida. ### Resultado primario Tasa de resolución correcta dentro de un presupuesto fijo. ### Resultados secundarios - superficie máxima; - área bajo la superficie; - tokens; - tiempo; - distancia al objetivo; - evidencia por unidad de superficie; - frecuencia de intentos de reescritura. ### Predicción previa Si la tesis es correcta: ```text éxito(D) > éxito(B) éxito(D) > éxito(C) superficie(D) < superficie(A) deriva(D) < deriva(A) ``` La comparación entre B y C indicará cuánto aporta estructura frente a observabilidad. No se presupone cuál domina. ## 19. Relación con Objective Guard Objective Guard debe construirse inicialmente como instrumento de medición pasivo. Durante la primera fase registra y puntúa trayectorias, pero no alerta al agente. Esto evita que el instrumento altere el fenómeno mientras calibramos sus métricas. El orden correcto es: ```text observar → operacionalizar → medir → calibrar → validar → intervenir ``` Sólo después de demostrar validez predictiva fuera de muestra se habilitan advertencias. Los bloqueos automáticos requieren además evidencia determinista o una política humana explícita.