# Capa 3 — Modelo de señales y decisión de Objective Guard ## Clases de señal ### Clase A — Hecho determinista Resultado reproducible por inspección o ejecución: - archivo no parsea; - assertion eliminada; - test deshabilitado; - contrato público incompatible; - comando focalizado falla; - dependencia agregada. Puede operar desde el primer día. Su severidad depende de política, no de probabilidad. ### Clase B — Evidencia incompleta Describe ausencia o insuficiencia: - bugfix sin reproducción; - criterio sin test ni contrato; - grafo de impacto parcial; - check requerido no ejecutado. Produce `unknown` o `block` en modo final si la política así lo establece. ### Clase C — Señal estadística Describe una trayectoria inusual frente a tareas comparables: - superficie extrema; - dispersión arquitectónica; - expansión acumulada; - evidencia que crece más lento que el cambio; - probabilidad anómala de intento de reescritura. Comienza en modo pasivo. No implica que el código esté mal. ### Clase D — Juicio asistido por modelo Puede proponer localización, clasificación, criterios o explicaciones. Nunca es bloqueante sin traducción a una clase A, B o política humana explícita. ## Superficie del cambio El repositorio se representa como un grafo tipado \(G=(V,E)\). Sus nodos pueden ser módulos, archivos o símbolos; las aristas representan imports, llamadas, herencia, eventos, datos y build. Para cada paso \(t\): \[ \mathbf{s}_t= [F_t,L_t,Y_t,M_t,P_t,D_t,H_t,C_t] \] | Variable | Significado | | --- | --- | | \(F_t\) | Archivos modificados. | | \(L_t\) | Churn de líneas. | | \(Y_t\) | Símbolos modificados. | | \(M_t\) | Módulos alcanzados. | | \(P_t\) | Fronteras públicas tocadas. | | \(D_t\) | Distancia respecto del conjunto objetivo. | | \(H_t\) | Entropía de distribución entre módulos. | | \(C_t\) | Centralidad de nodos modificados. | El conjunto objetivo \(O\) se conoce en benchmarks sembrados. En producción debe derivarse del contrato de sesión y puede ser incompleto. \[ 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)} \] La dispersión entre módulos se representa mediante: \[ H_t=-\sum_i p_i\log p_i \] Para capturar cambios transitorios que luego se revierten: \[ AUS=\sum_{t=1}^{T}S_t\Delta t \] Objective Guard conserva el vector completo. Una puntuación escalar puede priorizar, pero no debe ocultar qué factores explican la alerta. La primera instrumentación ejecutable usa `trajectory-features-v1`. Conserva (F,L,M,P,H) directamente del evento; (D) es por ahora `outside_scope_ratio`, un **proxy de distancia al objetivo** y no una distancia de grafo. Define una superficie descriptiva (S=F+L+M+P+D+H), con unidades heterogéneas que no deben interpretarse como riesgo ni como probabilidad. El AUS inicial es discreto por ronda, `AUS_round = Σ S_t`: no convierte períodos de inactividad humana en área. Estas fórmulas y ε = 10⁻⁶ se exportan junto a cada dataset para impedir recalibración implícita. ## Evidencia Cada criterio \(a_j\) posee estado y evidencia reproducible. Para investigación puede asignarse una fuerza ordinal predefinida: \[ e_j\in\{0,0.25,0.5,0.75,1\} \] La evidencia total es: \[ E_t=\sum_j q_je_{j,t} \] Los pesos \(q_j\) deben declararse antes de evaluar y someterse a análisis de sensibilidad. La relación evidencia-superficie es: \[ J_t=\frac{E_t+\epsilon}{S_t+\epsilon} \] Una señal relevante de deriva es: \[ \Delta S_t \gg \Delta E_t \] Esto significa que la solución expande su impacto sin demostrar proporcionalmente nuevos criterios. En `trajectory-features-v1`, todos los criterios requeridos tienen peso uniforme y `E = proven_required / required`; si no existen criterios requeridos, `E = 0`. Es una medida de cobertura reproducible, no evidencia semántica de que el criterio esté bien formulado. `J=(E+ε)/(S+ε)` se registra sin umbral, ranking ni alerta. Para comparación histórica se prefieren mediana, MAD y conformal prediction frente a una normalidad asumida. El p-value conformal: \[ p_t=\frac{1+\#\{i:A_i\ge A_t\}}{n+1} \] se interpreta como extremidad respecto de la muestra comparable, no como probabilidad de incorrección. ### Amplificación del cambio Objective Guard puede consumir una señal de amplificación del cambio provista por el proyecto que combina frecuencia histórica de cambio con una superficie de impacto: \[ A(v)=frecuencia(v)\times superficieImpacto(v) \] La entidad \(v\) puede ser un archivo, módulo, paquete, servicio u otra unidad estable. `superficieImpacto` la define un adaptador del repositorio o analizador externo y puede representar tests alcanzables, módulos downstream, pipelines, despliegues u otra unidad de impacto declarada. El core no asume lenguaje, convención de nombres, framework de tests, extractor de grafo ni que la amplificación mida tiempo real de CI. La señal conserva sus factores y baseline en lugar de exponer sólo el producto. Una evaluación temprana distingue: 1. una entidad modificada que ya era un outlier de amplificación en el baseline; 2. un incremento material de superficie de impacto durante la ronda actual; 3. un nuevo cruce hacia una región de outliers. Un incremento de frecuencia causado meramente por tocar una entidad no significa por sí solo que la arquitectura empeoró. Por eso, la intervención temprana prioriza el delta de `superficieImpacto` y el cruce de outlier; tocar un outlier preexistente es riesgo contextual. Las comparaciones usan cohortes declaradas y métodos robustos o conformales en lugar de una distribución normal sobre el producto crudo. Las cohortes pequeñas o no comparables reducen la confianza y no pueden degradar silenciosamente hacia una conclusión bloqueante. La historia completa, el grafo, las cohortes y la distribución de referencia se calculan fuera del camino crítico por edición y se almacenan como baseline versionado. Los checks tempranos evalúan las entidades cambiadas y su delta local de grafo contra ese baseline. Un proveedor informa procedencia, unidades, cobertura, huecos, confianza, valores de baseline y candidato, percentil o estadístico robusto y duración de cálculo. La cobertura faltante del proveedor permanece explícita. La amplificación comienza como telemetría pasiva. Las rondas grandes de desarrollo existentes pueden aportar trayectorias orgánicas para calibración, pero el volumen de telemetría por sí solo no autoriza una alerta. Después de validación fuera de muestra, la política puede mostrar una advertencia no bloqueante por incremento material o cruce de umbral. Sólo puede requerir justificación después de validación de intervención, y sólo puede bloquear cuando un criterio contractual explícito prohíbe el incremento o existe una violación determinista separada. ## Política de decisión ### Sustitución de objetivo `goal-substitution` es inicialmente una señal determinista de contrato, no estadística. Requiere simultáneamente: 1. contrato válido y política activa; 2. superficie material por archivos o churn; 3. cero evidencia observable para los KRs a los que la ronda declara contribuir; 4. al menos un archivo fuera del scope o dentro de un non-goal observable. Con política `warn` su severidad inicial es `warning` y nunca bloquea; con política `observe` queda registrada como observación sin advertir al agente. La ausencia de evidencia sin una desviación declarada no alerta, porque puede representar trabajo incremental legítimo. El plano estadístico recibe estas observaciones pasivamente y no cambia la decisión hasta alcanzar los gates pre-registrados. | Evidencia | Calibración | Decisión predeterminada | | --- | --- | --- | | Hecho determinista de severidad bloqueante | No requerida | `block` | | Hecho determinista no bloqueante | No requerida | `warn` | | Criterio requerido sin evidencia, modo rápido | No requerida | `unknown` | | Criterio requerido sin evidencia, modo final | Política explícita | `block` | | Señal estadística no calibrada | Ausente | Registrar, no alertar | | Señal calibrada moderada | Validada fuera de muestra | `warn` o ampliar checks | | Señal calibrada extrema | Validada con intervención | Pausar y requerir justificación | | Juicio de modelo | No aplicable | Propuesta sin autoridad | El veredicto debe incluir: ```json { "status": "block", "scope": "checks_executed_only", "new_findings": [], "criteria": [], "impact": {}, "checks_run": [], "checks_skipped": [], "duration_ms": 0, "reproduce": "oguard check --finding FINDING_ID" } ``` Un `pass` declara explícitamente qué fue verificado y qué quedó fuera.