# PRD: Objective Guard

## Estado del documento

- Estado: borrador inicial
- Tipo de producto: herramienta local/CI para agentes de programación
- Audiencia: equipos que usan agentes de IA para desarrollar, mantener y reparar software
- Nombre provisional: Objective Guard

## 1. Resumen ejecutivo

Objective Guard es un sistema programático de verificación continua para agentes de código. Su propósito es detectar, con la menor latencia posible, si un cambio:

1. se desvía del objetivo declarado;
2. rompe comportamiento o contratos existentes;
3. modifica una superficie mayor que la necesaria;
4. carece de evidencia suficiente para considerarse correcto.

El producto no intenta comprender exhaustivamente todo el repositorio ni reemplazar los tests, linters o analizadores existentes. Funciona como un plano de control que, para cada tarea, compone reglas globales, reglas del área afectada, evidencia extraída del repositorio y un contrato temporal de intención. A partir del diff y del grafo de impacto selecciona las verificaciones mínimas necesarias y devuelve un resultado estructurado y compacto al agente.

La premisa de escalabilidad es:

> El costo de validación debe crecer con el radio de impacto del cambio, no con el tamaño total del repositorio.

## 2. Problema

Los agentes de programación pueden producir código sintácticamente correcto y aun así:

- resolver una variante distinta del problema solicitado;
- ampliar el alcance sin necesidad;
- romper contratos públicos o invariantes no evidentes;
- introducir una regresión en un módulo dependiente;
- declarar éxito sin aportar evidencia verificable;
- gastar contexto y tokens antes de descubrir un error básico.

Las herramientas existentes validan dimensiones aisladas —compilación, estilo, tests o seguridad—, pero normalmente no relacionan esas señales con la intención concreta de la tarea. Por otro lado, describir manualmente todo un repositorio mediante reglas detalladas es costoso y se degrada rápidamente.

## 3. Objetivo del producto

Proporcionar a cualquier agente de programación un ciclo de feedback determinista, incremental y de baja latencia que responda:

- ¿El cambio continúa alineado con el objetivo?
- ¿Qué contratos o áreas puede afectar?
- ¿Qué evidencia falta para demostrar que está terminado?
- ¿Debe continuar, corregir o pedir una decisión humana?

## 4. No objetivos

Objective Guard no pretende:

- demostrar formalmente que cualquier programa es correcto;
- reemplazar el razonamiento del agente o la revisión humana;
- mantener una especificación manual exhaustiva del repositorio;
- ejecutar siempre toda la suite de CI;
- decidir requisitos de producto ambiguos sin intervención humana;
- usar un segundo modelo como autoridad final sobre la corrección.

Puede utilizar modelos para proponer clasificaciones o contratos, pero una regla generada por IA solo será bloqueante cuando se traduzca a evidencia o comprobaciones reproducibles.

## 5. Usuarios y casos de uso

### 5.1 Usuario principal

Un agente de programación que inspecciona, edita y verifica código mediante herramientas locales.

### 5.2 Usuarios secundarios

- Desarrolladores que supervisan al agente.
- Equipos de plataforma que definen políticas globales.
- Responsables de módulos que mantienen invariantes locales.
- CI, utilizado como verificación final de las mismas reglas.

### 5.3 Tipos de tarea soportados

| Tipo | Prueba mínima esperada |
| --- | --- |
| `feature` | El comportamiento nuevo existe y el comportamiento previo relevante se conserva. |
| `bugfix` | Existe una reproducción del fallo y pasa después del cambio; se cubren regresiones cercanas. |
| `refactor` | El comportamiento observable se conserva dentro de la superficie afectada. |
| `improvement` | Una métrica definida mejora respecto de un baseline sin degradaciones prohibidas. |
| `migration` | El estado o contrato migra de A a B con estrategia de compatibilidad y recuperación. |
| `maintenance` | El cambio operativo o de dependencias satisface compatibilidad, seguridad y build. |
| `investigation` | Se produce evidencia y conclusiones; no se habilitan cambios productivos implícitos. |

Si la intención es ambigua, el sistema utiliza el estado `discovery`. En ese estado permite inspección y propuesta del contrato, pero alerta antes de modificaciones productivas de alto impacto.

## 6. Principios de diseño

### 6.1 Contratos compuestos

El contrato efectivo de una tarea se construye mediante capas:

1. Políticas globales: seguridad, secretos, licencias, límites arquitectónicos y comandos base.
2. Políticas del módulo: contratos públicos, invariantes y verificaciones propias del área.
3. Contrato de tarea: intención, alcance esperado, criterios de aceptación y restricciones temporales.
4. Evidencia inferida: manifiestos, tipos, OpenAPI, esquemas, CODEOWNERS, tests y grafo de dependencias.

Las capas más específicas pueden agregar restricciones. Una excepción a una política superior debe ser explícita, trazable y, cuando corresponda, aprobada.

### 6.2 Validación incremental

Los checks baratos se ejecutan primero. Las verificaciones costosas se activan según riesgo e impacto.

### 6.3 Determinismo auditable

Cada `block` debe indicar regla, evidencia, archivo, ubicación y forma de reproducción. Una inferencia probabilística puede producir `warn` o proponer una regla, pero no bloquear por sí sola.

### 6.4 Salida optimizada para agentes

La salida primaria es JSON estable, breve y accionable. La explicación humana es una vista secundaria.

### 6.5 Degradación segura

Si no existe información suficiente, el sistema debe decir `unknown` o solicitar evidencia. No debe convertir ausencia de conocimiento en una afirmación de corrección.

## 7. Experiencia del producto

### 7.1 Inicio de tarea

El agente registra o genera una sesión:

```bash
oguard start \
  --kind bugfix \
  --goal "Corregir el checkout cuando el cupón está expirado" \
  --acceptance "El checkout continúa sin aplicar el cupón"
```

Objective Guard inspecciona el repositorio, identifica el área probable y genera un contrato de sesión. El agente puede ampliarlo o corregirlo antes de editar.

### 7.2 Ciclo rápido

Después de cada patch significativo:

```bash
oguard check --staged-or-working-tree --mode fast --format json
```

Respuesta esperada:

```json
{
  "status": "block",
  "session": "og_01J...",
  "impact": {
    "risk": "high",
    "modules": ["checkout", "pricing"],
    "public_boundaries": ["CheckoutService.complete"]
  },
  "violations": [
    {
      "rule_id": "checkout.tax-invariant",
      "severity": "block",
      "file": "src/checkout/total.ts",
      "line": 48,
      "message": "El cálculo de impuestos cambió fuera del objetivo.",
      "evidence": "contract-test checkout-tax: expected 21.00, received 19.50",
      "next_action": "Restaurar el cálculo o declarar una ampliación de alcance."
    }
  ],
  "checks_run": 7,
  "checks_skipped": 18,
  "duration_ms": 1830
}
```

### 7.3 Verificación final

Antes de declarar la tarea terminada:

```bash
oguard check --mode final
```

El modo final exige evidencia para cada criterio de aceptación y ejecuta verificaciones de mayor cobertura dentro del radio de impacto.

## 8. Requisitos funcionales

### RF-1: Sesión de objetivo

El sistema debe crear una sesión aislada que contenga:

- objetivo textual;
- tipo de tarea;
- criterios de aceptación;
- restricciones explícitas;
- commit o estado usado como baseline;
- estado actual de validación.

### RF-2: Clasificación de intención

Debe aceptar una clasificación explícita y puede sugerirla automáticamente. Si la confianza o la información son insuficientes, debe seleccionar `discovery`.

### RF-3: Descubrimiento del repositorio

Debe detectar, mediante adaptadores:

- lenguaje, sistema de build y gestor de paquetes;
- módulos o workspaces;
- comandos existentes de test, typecheck y lint;
- archivos de contratos públicos;
- ownership y límites arquitectónicos;
- tests relacionados y cobertura, cuando esté disponible.

### RF-4: Cálculo del radio de impacto

A partir del diff debe identificar:

- símbolos cambiados;
- módulos propietarios y dependientes;
- APIs, esquemas, migraciones o eventos afectados;
- tests directa e indirectamente relacionados;
- nivel de riesgo del cambio.

El sistema debe tolerar un grafo parcial y declarar la incertidumbre.

### RF-5: Planificación de verificaciones

Debe seleccionar checks según una combinación de:

- tipo de tarea;
- archivos y símbolos modificados;
- reglas aplicables;
- fronteras públicas afectadas;
- costo histórico del check;
- riesgo e incertidumbre.

### RF-6: Ejecución de checks

Debe soportar inicialmente:

- reglas sobre paths y tamaño del diff;
- búsqueda de patrones prohibidos;
- comandos del repositorio;
- tests focalizados;
- typecheck y lint focalizados;
- comparación de OpenAPI/JSON Schema;
- comparación de exports o firmas públicas;
- reglas AST mediante plugins;
- validación de que un bugfix incluye reproducción o test de regresión.

### RF-7: Trazabilidad

Cada criterio de aceptación debe terminar en uno de estos estados:

- `proven`: existe evidencia reproducible;
- `violated`: existe evidencia en contra;
- `unknown`: todavía no hay evidencia suficiente;
- `not_applicable`: justificado explícitamente.

### RF-8: Presupuesto de deriva

Debe calcular señales independientes, no una única puntuación opaca:

- expansión de alcance;
- cambio en fronteras públicas;
- archivos no relacionados;
- dependencias nuevas;
- criterios sin evidencia;
- riesgo acumulado del diff.

Una política puede convertir combinaciones de señales en `warn` o `block`.

### RF-9: Excepciones

El agente puede solicitar una excepción, pero debe incluir motivo, regla afectada y alcance. Las excepciones quedan registradas en la sesión y pueden requerir aprobación humana según política.

### RF-10: Integraciones

El MVP debe funcionar mediante:

- CLI local;
- hook invocable por agentes después de editar;
- salida JSON por `stdout`;
- código de salida estable para `pass`, `warn`, `block` y `error`;
- ejecución en CI usando el mismo contrato.

## 9. Requisitos no funcionales

### Latencia

- Modo `fast`: p50 menor a 2 segundos y p95 menor a 8 segundos en checks cacheados.
- Primera inspección: objetivo menor a 30 segundos para repositorios medianos.
- El sistema debe emitir resultados parciales cuando un check largo continúa ejecutándose.

### Escalabilidad

- No debe requerir indexar todo el repositorio en cada ejecución.
- Debe almacenar índices por commit y actualizar solo archivos cambiados.
- Debe soportar monorepos con decenas de miles de archivos mediante adaptadores por workspace.

### Reproducibilidad

- Cada resultado debe registrar versión de reglas, baseline, comando y hash de entradas relevantes.
- Un check determinista debe poder reproducirse fuera del agente.

### Seguridad

- Los comandos deben ejecutarse con límites de tiempo y recursos.
- El motor no debe enviar código a servicios externos por defecto.
- Los plugins deben declarar permisos y capacidades.

## 10. Modelo de contrato

Ejemplo orientativo:

```yaml
version: 1
session:
  kind: bugfix
  goal: Corregir el checkout cuando el cupón está expirado
  baseline: git:HEAD

acceptance:
  - id: expired-coupon
    statement: El checkout continúa sin aplicar un cupón expirado
    evidence:
      require:
        - test: checkout.expired_coupon
  - id: valid-coupon
    statement: Los cupones vigentes continúan aplicándose
    evidence:
      require:
        - test: checkout.valid_coupon

scope:
  expected:
    - packages/checkout/**
  sensitive:
    - packages/pricing/**
    - packages/tax/**

invariants:
  - id: no-tax-change
    source: module:tax
    check: contract-test
  - id: public-api-compatible
    source: inferred:typescript-exports
    check: api-diff

policy:
  unknown_acceptance: block_on_final
  public_boundary_change: require_approval
```

Este archivo representa el contrato compilado. La interfaz de usuario puede aceptar lenguaje natural, pero el motor opera sobre una representación estructurada.

## 11. Aproximación técnica

### 11.1 Arquitectura

```text
Agent / Developer / CI
          |
          v
       CLI/API
          |
          v
   Session & Contract Compiler
      |        |         |
      v        v         v
 Policy     Repo      Task-type
 Loader   Discovery    Adapter
      \        |         /
       v       v        v
        Impact Analyzer
          |
          v
       Check Planner
          |
          v
      Runner Scheduler
       |     |      |
      AST  Commands Contracts
       \     |      /
        v    v     v
      Evidence Store
          |
          v
      Verdict Engine
          |
          v
  JSON result + exit code
```

### 11.2 Componentes

#### Contract Compiler

Fusiona políticas globales, políticas jerárquicas del repositorio, contrato de sesión e inferencias. Produce una lista normalizada de reglas con precedencia y procedencia.

#### Repository Discovery

Utiliza adaptadores para reconocer Gradle, Maven, npm/pnpm/bun, Cargo u otros ecosistemas. No interpreta el negocio; descubre comandos, unidades de build y metadatos.

#### Impact Analyzer

El MVP puede comenzar con paths, imports y manifiestos. Versiones posteriores agregan análisis de símbolos mediante Tree-sitter o servidores de lenguaje. Su salida debe incluir nivel de confianza para evitar falsa precisión.

#### Check Planner

Resuelve qué checks ejecutar mediante reglas explícitas. Ejemplo:

```text
IF task.kind == bugfix
AND changed.module == checkout
THEN require regression-test(checkout)

IF public_api.changed
THEN run api-diff
AND require approval when breaking
```

No se recomienda que un LLM sea el planificador definitivo. Puede sugerir checks, pero el plan final debe ser inspeccionable.

#### Runner Scheduler

Ejecuta primero checks baratos y paralelizables, cancela trabajo innecesario ante bloqueos concluyentes y reutiliza caché por hash de entradas.

#### Evidence Store

Una base SQLite local es suficiente para el MVP. Debe almacenar sesiones, reglas compiladas, ejecuciones, duración, hashes y relación entre criterios y evidencia. Los artefactos pesados pueden permanecer en archivos direccionados por contenido.

#### Verdict Engine

Aplica políticas deterministas sobre resultados. Debe mantener separados:

- hechos: “cambió una firma pública”;
- inferencias: “probablemente este archivo no pertenece al objetivo”;
- decisiones: “un cambio público requiere aprobación”.

### 11.3 Stack sugerido

Para un MVP portable:

- Lenguaje: Rust o TypeScript.
- Recomendación inicial: TypeScript para iteración e integración rápida con agentes; migrar runners críticos solo si las métricas lo justifican.
- Persistencia: SQLite.
- Parsing multi-lenguaje: Tree-sitter.
- Contratos: JSON Schema para validar configuración.
- Ejecución: procesos locales aislados con timeout.
- Distribución: binario empaquetado o paquete npm con ejecutable.

La arquitectura debe mantener el core independiente del ecosistema mediante interfaces de plugins.

### 11.4 Interfaces principales

```ts
interface RepositoryAdapter {
  discover(root: string): Promise<RepositoryModel>;
  affectedUnits(diff: Diff): Promise<ImpactSet>;
}

interface CheckProvider {
  plan(context: CheckContext): Promise<PlannedCheck[]>;
  run(check: PlannedCheck, signal: AbortSignal): Promise<Evidence>;
}

interface PolicyRule {
  evaluate(facts: FactSet): VerdictContribution;
}
```

### 11.5 Estrategia incremental y caché

La clave de caché de un check debe incluir:

```text
hash(
  check-version,
  command-or-rule,
  relevant-input-files,
  dependency-manifests,
  environment-fingerprint
)
```

El índice de imports y símbolos se actualiza solo para los archivos cambiados. El sistema invalida consumidores únicamente cuando cambia una frontera exportada; un cambio interno no debe propagar automáticamente la validación a todo el repositorio.

## 12. MVP

### Alcance

El MVP debe validar una tarea sobre repositorios Git de TypeScript/JavaScript y ofrecer:

1. sesiones con `feature`, `bugfix`, `refactor` e `improvement`;
2. contrato YAML validado por schema;
3. análisis de `git diff` y reglas de paths;
4. descubrimiento de workspaces y scripts de package managers;
5. selección de tests por workspace y archivos relacionados;
6. ejecución de lint, typecheck y tests existentes;
7. detección básica de exports públicos modificados;
8. trazabilidad criterio-evidencia;
9. modos `fast` y `final`;
10. salida JSON y códigos de salida documentados;
11. caché local SQLite;
12. integración genérica por hook para agentes.

### Fuera del MVP

- Generación automática confiable de invariantes de negocio.
- Soporte profundo para todos los lenguajes.
- Análisis interservicio distribuido.
- Dashboard centralizado.
- Autoaprobación de cambios de alcance.

### Criterios de aceptación del MVP

- En un bugfix de ejemplo, bloquea el cierre si no existe evidencia de regresión.
- En una feature, detecta un cambio incompatible en un export público.
- En un refactor interno, evita ejecutar tests de workspaces no afectados.
- Una segunda ejecución sin cambios es al menos 70 % más rápida.
- Todo bloqueo incluye una reproducción local y una acción sugerida.
- Puede integrarse con un agente usando un único comando y JSON por stdout.

## 13. Métricas

### Métrica principal

Porcentaje de desviaciones o regresiones detectadas antes de que el agente complete la tarea.

### Métricas operativas

- tiempo hasta la primera señal útil;
- porcentaje de checks evitados frente a CI completa;
- tasa de falsos bloqueos;
- tasa de tareas cerradas con criterios `unknown`;
- cantidad de correcciones realizadas dentro de los dos patches posteriores a una alerta;
- tokens o turnos consumidos después de introducir un defecto y antes de detectarlo;
- hit rate de caché;
- duración p50/p95 por modo.

### Objetivos iniciales

- Detectar al menos 70 % de las regresiones sembradas dentro del alcance soportado.
- Mantener falsos bloqueos por debajo de 5 %.
- Emitir la primera señal determinista en menos de 2 segundos p50.
- Reducir al menos 50 % los checks ejecutados respecto de la suite completa en cambios locales.

## 14. Riesgos y mitigaciones

| Riesgo | Mitigación |
| --- | --- |
| Sensación falsa de corrección | Usar `unknown` explícito y reportar cobertura de evidencia. |
| Reglas difíciles de mantener | Inferir configuración, mantener pocas políticas en fronteras críticas y medir reglas sin uso. |
| Falsos positivos que el agente aprende a ignorar | Separar `warn` de `block`; exigir evidencia reproducible para bloquear. |
| Grafo de impacto incompleto | Propagar confianza; ampliar checks cuando la incertidumbre sea alta. |
| Latencia excesiva | Etapas fast/final, caché, paralelismo y cancelación temprana. |
| Contrato generado que cambia el objetivo | Conservar el pedido original, mostrar el contrato derivado y registrar ampliaciones. |
| Plugins ejecutando comandos inseguros | Capacidades declaradas, sandbox, timeout y allowlists. |
| Adopción costosa | Funcionar inicialmente con scripts y metadatos ya presentes en el repositorio. |

## 15. Roadmap propuesto

### Fase 0: prototipo

- Contrato YAML.
- Diff por paths.
- Runner de comandos.
- Veredicto JSON.
- Un repositorio de prueba con escenarios sembrados.

### Fase 1: MVP

- Adaptador TypeScript/JavaScript.
- Workspaces, tests afectados, exports públicos y SQLite.
- Integración con al menos un agente de código.
- Benchmark de latencia y precisión.

### Fase 2: precisión

- Índice AST/símbolos.
- Compatibilidad OpenAPI/JSON Schema.
- Aprendizaje estadístico solo para priorización de checks.
- Herramientas para explicar e inspeccionar el plan.

### Fase 3: ecosistema

- SDK de plugins.
- Adaptadores Java/Gradle, Python y Rust.
- Ejecución distribuida y reutilización de resultados de CI.
- Políticas organizacionales firmadas.

## 16. Preguntas abiertas

- ¿Cuál será el primer agente o protocolo de integración objetivo?
- ¿El contrato de tarea debe persistirse en Git o vivir como artefacto efímero?
- ¿Qué nivel de intervención humana se requiere para ampliar alcance?
- ¿Cómo se identifica un test de regresión nuevo frente a uno preexistente?
- ¿Qué ecosistema representa mejor el repositorio piloto?
- ¿Qué restricciones de sandbox y red deben considerarse desde el primer release?

## 17. Primera validación experimental

Antes de construir el producto completo se recomienda crear un benchmark con 30 tareas reales o sintetizadas, equilibradas entre feature, bugfix, refactor e improvement. Para cada tarea se prepara:

- objetivo y criterios;
- cambio correcto;
- una o más desviaciones sembradas;
- checks que deberían activarse;
- radio de impacto esperado;
- tiempo máximo aceptable para la primera alerta.

El prototipo se considera prometedor si detecta desviaciones temprano sin recurrir a una suite completa y mantiene una tasa baja de bloqueos no accionables. Este benchmark debe evolucionar como contrato del propio producto.

El diseño experimental completo, sus hipótesis falsables, variables, controles y plan estadístico se definen en [Protocolo científico: deriva de agentes en repositorios en crecimiento](research-protocol-agent-drift.es.md).