# Capacidades y flujos de Objective Guard

Cada capacidad distingue comportamiento observado `[Hecho]`, deducciones `[Inferencia]` y huecos `[Ambigüedad]`. CAP-02, CAP-10 y CAP-11 poseen implementación ejecutable parcial o completa; las demás describen el producto planificado.

### CAP-01 — Recibir feedback inmediato después de una edición

- Actor: agente de programación.
- Superficie: hook por edición.
- Objetivo: conocer una violación local antes de construir nuevos pasos sobre ella.
- Precondiciones: hook instalado; archivo dentro de un repositorio soportado.
- Trigger: escritura o edición completada por el agente.
- Flujo principal:
  1. El hook recibe el archivo modificado.
  2. Objective Guard obtiene contenido y diff relevante.
  3. Ejecuta detectores universales con timeout.
  4. Compara fingerprints con el estado anterior.
  5. Emite sólo hallazgos nuevos y registra el evento.
- Variantes / errores observables: [Inferencia] sin hallazgos no emite ruido; [Inferencia] timeout registra `error` y no bloquea; [Ambigüedad] formato exacto del hook depende del primer harness.
- Resultado esperado: el agente recibe un delta compacto dentro del presupuesto de latencia.
- Reglas / permisos implicados: nivel 0 no requiere contrato; máximo cinco líneas; `error` no equivale a `pass`.
- Datos / entidades tocadas: archivo, diff, fingerprint, evento, estado local.
- Evidencia: `docs/product/02-product-contract.es.md` RF-01 a RF-04; `docs/product/04-technical-architecture.es.md` Nivel 0.
- Huecos abiertos: elegir harness inicial y medir latencia real.

### CAP-02 — Detectar deriva universal sin configuración

- Actor: agente de programación.
- Superficie: hook y CLI local.
- Objetivo: detectar patrones objetivamente riesgosos aunque no exista contrato de tarea.
- Precondiciones: diff disponible; lenguaje o manifest soportado por el detector.
- Trigger: ejecución del nivel 0.
- Flujo principal:
  1. Analiza sintaxis del archivo.
  2. Compara tests antes y después.
  3. Busca stubs nuevos en producción.
  4. Inspecciona manifests por dependencias nuevas.
  5. Produce hechos separados por regla.
- Variantes / errores observables: [Inferencia] archivos no soportados se reportan como fuera de alcance; [Inferencia] una dependencia nueva comienza como warning; [Ambigüedad] heurística inicial de caída de assertions.
- Resultado esperado: cada hecho incluye regla, archivo, ubicación y reproducción.
- Reglas / permisos implicados: un test deshabilitado puede bloquear; un stub o dependencia sólo advierte por defecto.
- Datos / entidades tocadas: AST, manifests, tests, diff, findings.
- Evidencia: `docs/product/06-roadmap-and-criteria.es.md` MVP y criterios funcionales.
- Huecos abiertos: construir corpus golden JS/TS y decidir soporte Java.

### CAP-03 — Evitar repetición de hallazgos conocidos

- Actor: agente de programación.
- Superficie: hook y almacenamiento local.
- Objetivo: ahorrar tokens y prevenir fatiga por warnings repetidos.
- Precondiciones: hallazgo fingerprintable; estado local accesible.
- Trigger: un detector produce un hallazgo.
- Flujo principal:
  1. Normaliza regla, archivo, ventana y mensaje.
  2. Calcula fingerprint versionado.
  3. Compara con fingerprints activos.
  4. Emite únicamente novedades.
  5. Resume resoluciones y actualiza estado.
- Variantes / errores observables: [Inferencia] estado borrado puede re-reportar; [Inferencia] estado corrupto no debe causar silencio; [Ambigüedad] política de migración entre versiones de regla.
- Resultado esperado: ejecuciones consecutivas sin cambios no repiten el mismo hallazgo.
- Reglas / permisos implicados: estado descartable; delta-only obligatorio.
- Datos / entidades tocadas: fingerprints, versión de regla, state.json.
- Evidencia: `docs/product/04-technical-architecture.es.md` Persistencia y protocolo.
- Huecos abiertos: definir normalización exacta de ventanas y movimientos de archivo.

### CAP-04 — Formalizar una tarea mediante un contrato de sesión

- Actor: desarrollador supervisor y agente de programación.
- Superficie: CLI y contrato de sesión.
- Objetivo: volver observables objetivo, alcance, criterios e invariantes.
- Precondiciones: pedido original disponible; repositorio descubierto al menos parcialmente.
- Trigger: inicio explícito de una sesión o transición desde `discovery`.
- Flujo principal:
  1. Conserva el objetivo original sin reescribirlo.
  2. Registra tipo de tarea y criterios.
  3. Declara conjunto objetivo, scope y zonas sensibles.
  4. Compone políticas globales y locales.
  5. Valida y versiona el contrato compilado.
- Variante de transición [Hecho]: `next-round` requiere árbol limpio y baseline coincidente, archiva contrato/baseline previos y registra `round-transition` antes de activar el nuevo contrato.
- Variante de migración [Hecho]: `adopt-baseline` permite una única adopción de contrato tipado histórico con árbol limpio; conserva el contrato y registra `baseline-adopted`.
- Variantes / errores observables: [Inferencia] ambigüedad produce `discovery`; [Inferencia] conflicto de políticas muestra procedencia; [Ambigüedad] formato YAML o JSON.
- Resultado esperado: existe un contrato trazable que habilita checks específicos sin ocultar incertidumbre.
- Reglas / permisos implicados: políticas superiores no se relajan implícitamente; ampliaciones quedan registradas.
- Datos / entidades tocadas: sesión, objetivo, criterios, scope, invariantes, policy rules.
- Evidencia: `docs/product/02-product-contract.es.md` Nivel 1 y RF-05 a RF-07.
- Huecos abiertos: UX de confirmación, jerarquía de rondas remotas y esquema externo definitivo.

### CAP-05 — Ejecutar una verificación incremental afectada

- Actor: agente de programación.
- Superficie: CLI local por save o turno.
- Objetivo: obtener evidencia relevante sin ejecutar toda la suite.
- Precondiciones: diff disponible; adaptador del repositorio detecta unidades y comandos.
- Trigger: `oguard round-end --mode fast` o checkpoint automático.
- Flujo principal:
  1. Calcula paths, imports relativos estáticos, módulos y fronteras públicas declaradas afectadas.
  2. Declara incertidumbre del grafo.
  3. Planifica checks inspeccionables.
  4. Ejecuta sólo los checks declarados para `fast` (o sin restricción de modo).
  5. Reutiliza caché y actualiza evidencia.
- Variantes / errores observables: [Inferencia] incertidumbre alta amplía checks; [Inferencia] cache miss aumenta latencia; [Ambigüedad] selección inicial de tests por ecosistema.
- Resultado esperado: veredicto rápido con checks ejecutados, omitidos, `mode: fast` y alcance declarado; un criterio requerido desconocido permanece `unknown`.
- Reglas / permisos implicados: costo proporcional a impacto; ningún check omitido se presenta como aprobado.
- Datos / entidades tocadas: grafo, planned checks, cache keys, evidence.
- Evidencia: `docs/product/04-technical-architecture.es.md` Nivel 1.
- Huecos abiertos: [Hecho] el adaptador Node propaga imports relativos estáticos de JS/MJS/CJS hacia consumidores transitivos y, para fronteras públicas declaradas por path, hacia los workspaces consumidores exactos; una dependencia de workspace no amplía sola el impacto de un archivo interno. Los checks declarados reutilizan caché local sólo con inputs, contrato y entorno idénticos. [Ambigüedad] faltan aliases, imports dinámicos, TypeScript, símbolos, caché distribuida y un umbral calibrado de propagación pública.

### CAP-06 — Cerrar una tarea con trazabilidad completa

- Actor: agente de programación y desarrollador supervisor.
- Superficie: CLI modo final e integración CI.
- Objetivo: demostrar qué criterios fueron probados y cuáles permanecen desconocidos.
- Precondiciones: sesión activa; criterios definidos; cambios disponibles.
- Trigger: solicitud de cierre o verificación en CI mediante `oguard round-end --mode final`.
- Flujo principal:
  1. Recorre cada criterio de aceptación.
  2. Vincula tests, contratos o comandos reproducibles.
  3. Ejecuta checks declarados para `final` (o sin restricción de modo).
  4. Marca `proven`, `violated`, `unknown` o `not_applicable`.
  5. Emite artefacto auditable y veredicto.
- Variantes / errores observables: [Hecho] todo criterio requerido `unknown` bloquea en `final`; checks fuera de modo quedan `skipped` y no se aprueban; [Inferencia] excepción conserva el hecho; [Ambigüedad] formato del artefacto CI.
- Resultado esperado: ningún criterio desaparece silenciosamente del cierre.
- Reglas / permisos implicados: `not_applicable` requiere justificación; error de runner no cuenta como evidencia positiva.
- Datos / entidades tocadas: criterios, evidencias, excepciones, final report.
- Evidencia: `docs/product/02-product-contract.es.md` RF-10 a RF-13.
- Huecos abiertos: [Hecho] obligaciones de feature, refactor, improvement, migration e investigation referencian criterios versionados y bloquean el cierre si faltan; [Ambigüedad] faltan retención y firma de artefactos.

### CAP-07 — Solicitar y auditar una excepción

- Actor: agente de programación y desarrollador supervisor.
- Superficie: CLI o mecanismo de aprobación.
- Objetivo: permitir una ampliación legítima sin borrar la violación observada.
- Precondiciones: hallazgo o política identificada; actor con autoridad disponible.
- Trigger: solicitud explícita de excepción.
- Flujo principal:
  1. Registra regla, motivo y alcance.
  2. Identifica actor aprobador y expiración.
  3. Evalúa si la política permite excepción.
  4. Conserva el hecho original.
  5. Modifica únicamente la decisión y audita el resultado.
- Variantes / errores observables: [Inferencia] autoridad insuficiente rechaza; [Inferencia] excepción expirada vuelve a aplicar; [Ambigüedad] integración con identidad externa.
- Resultado esperado: el trabajo puede continuar sólo dentro del alcance aprobado y sin perder trazabilidad.
- Reglas / permisos implicados: no hay autoaprobación de cambios sensibles; una excepción no convierte una violación en `pass` histórico.
- Datos / entidades tocadas: finding, policy decision, actor, approval, expiration.
- Evidencia: `docs/product/02-product-contract.es.md` RF-11.
- Huecos abiertos: [Hecho] la excepción local versionada exige regla, motivo, actor, expiración y paths; conserva el warning y sólo exceptúa la decisión; [Ambigüedad] faltan identidad externa, aprobación remota y almacenamiento de aprobaciones.

### CAP-08 — Medir deriva sin influir inicialmente en el agente

- Actor: investigador o evaluador.
- Superficie: event log y reporte científico offline.
- Objetivo: calibrar superficie y evidencia antes de activar alertas estadísticas.
- Precondiciones: trayectorias append-only; labels o outcomes; separación de datasets.
- Trigger: análisis offline periódico o benchmark.
- Flujo principal:
  1. Reconstruye la trayectoria completa.
  2. [Hecho] calcula vector de superficie, AUS discreta por ronda, proxy de distancia por scope y evidencia relativa con fórmulas versionadas.
  3. [Hecho] exporta particiones pasivas, disjuntas y deterministas `calibration` / `evaluation`.
  4. [Inferencia] compara con baselines simples.
  5. [Inferencia] calibra en repositorios de entrenamiento y evalúa en repositorios no vistos.
- Variantes / errores observables: [Inferencia] ground truth ausente limita distancia; [Inferencia] muestra insuficiente impide activar; [Ambigüedad] requisitos de anonimización entre organizaciones.
- Resultado esperado: dataset reproducible que puede concluir que la señal no sirve, sin cambiar el veredicto de la ronda.
- Reglas / permisos implicados: estadísticas pasivas hasta validación; no ajustar umbrales sobre test final.
- Datos / entidades tocadas: events, features, labels, calibration set, evaluation set.
- Evidencia: `synthetic/scenarios/task-trajectories-v1.mjs`; `synthetic/results/task-trajectories-v1.json`; `docs/product/05-scientific-validation.es.md` Escalera de evidencia.
- Huecos abiertos: volumen real mínimo, evaluación fuera de muestra y política de privacidad.

### CAP-09 — Intervenir con una señal estadística validada

- Actor: agente de programación y desarrollador supervisor.
- Superficie: hook o CLI.
- Objetivo: pausar expansiones anómalas antes de que se vuelvan terminales.
- Precondiciones: detector calibrado fuera de muestra; ensayo de intervención aprobado; política activa.
- Trigger: trayectoria atraviesa umbral pre-registrado.
- Flujo principal:
  1. Calcula no conformidad con versión congelada.
  2. Explica factores principales.
  3. Distingue anomalía de incorrección.
  4. Amplía checks o solicita justificación.
  5. Registra la respuesta y el desenlace.
- Variantes / errores observables: [Inferencia] señal moderada sólo advierte; [Inferencia] drift de distribución desactiva gobernanza; [Ambigüedad] frecuencia de recalibración.
- Resultado esperado: reducción de costo neto sin disminuir resolución correcta.
- Reglas / permisos implicados: nunca bloquear sólo por score opaco; umbrales versionados.
- Datos / entidades tocadas: feature vector, calibration version, alert, response, outcome.
- Evidencia: `docs/product/03-signal-and-decision-model.es.md` Política de decisión; `docs/product/05-scientific-validation.es.md` H5.
- Huecos abiertos: evidencia empírica todavía inexistente.

### CAP-10 — Validar la documentación contra su contrato

- Actor: equipo de plataforma.
- Superficie: guard documental.
- Objetivo: impedir que la documentación pierda capas, campos o enlaces requeridos.
- Precondiciones: Node.js disponible; ejecución desde raíz del repositorio.
- Trigger: `node scripts/validate-docs.mjs`.
- Flujo principal:
  1. Verifica archivos canónicos e históricos.
  2. Comprueba headings contractuales.
  3. Valida campos de cada capacidad.
  4. Valida matriz y enlaces relativos.
  5. Devuelve `PASS` o `BLOCK` con causas.
- Variantes / errores observables: [Hecho] archivos ausentes producen exit code 1; [Hecho] un enlace relativo roto bloquea; [Ambigüedad] todavía no valida semántica completa.
- Resultado esperado: sólo se acepta una topología documental que satisface el contrato codificado.
- Reglas / permisos implicados: no modifica documentos; resultado reproducible localmente.
- Datos / entidades tocadas: archivos Markdown y contrato embebido en el script.
- Evidencia: `scripts/validate-docs.mjs` funciones de archivos requeridos, capacidades, matriz y links.
- Huecos abiertos: agregar schema externo si el contrato crece.

### CAP-11 — Evaluar contribución de una ronda a objetivos jerárquicos

- Actor: agente de programación y desarrollador supervisor.
- Superficie: `oguard align`, `npm run round:end`, contrato `oguard.contract.json` y evidencia versionada.
- Objetivo: advertir progreso local material que no aporta evidencia a los KRs objetivo y además atraviesa un límite declarado de scope o non-goal.
- Precondiciones: [Hecho] repositorio Git; contrato schema v1 válido; diff contra `HEAD`; KRs con patrones de evidencia; política `goal_substitution` configurada.
- Trigger: consulta temprana `oguard align` después de un patch o cierre de una ronda mediante `npm run round:end`.
- Flujo principal:
  1. [Hecho] carga el objetivo padre, objetivo de ronda, KRs, scope, non-goals y umbrales.
  2. [Hecho] mide archivos, líneas agregadas/eliminadas, churn, módulos, entropía y archivos fuera de scope.
  3. [Hecho] atribuye archivos modificados como candidatos de evidencia a cada KR objetivo.
  4. [Hecho] imprime recordatorio compacto de objetivo, ronda, superficie y evidencia por KR.
  5. [Hecho] emite un único warning `goal-substitution` si coinciden superficie material, cero evidencia para KRs objetivo y desviación observable de scope/non-goal.
  6. [Hecho] registra hash del contrato, superficie y alineación; el export elimina textos y paths sensibles.
- Variantes / errores observables: [Hecho] contrato inválido termina con error; [Hecho] contrato ausente conserva los checks existentes sin evaluar alineación; [Hecho] trabajo incremental dentro de scope sin evidencia no alerta; [Hecho] evidencia del KR objetivo suprime la alerta; [Hecho] cambio inferior a ambos umbrales no alerta.
- Resultado esperado: el agente recibe una advertencia explicable y no bloqueante cuando el cambio reproduce sustitución de objetivo; una ronda alineada informa contribución sin ruido.
- Reglas / permisos implicados: warning con exit 0; paths modificados son candidatos, no prueba semántica del KR; señal estadística permanece pasiva; IDs y jerarquía inválidos no se aceptan.
- Datos / entidades tocadas: contrato versionado, hash, diff, vector de superficie, contribuciones por KR, warnings y event log.
- Evidencia: `src/contract.mjs` `validateContract`; `src/surface.mjs` `measureSurface`; `src/alignment.mjs` `evaluateAlignment`; `test/alignment.test.mjs`; `synthetic/scenarios/e001-goal-substitution.json`.
- Huecos abiertos: [Ambigüedad] evidencia `proven` todavía no se distingue de candidato por path; [Ambigüedad] distancia semántica e imports quedan para una fase posterior; [Ambigüedad] umbrales estadísticos no se activan hasta alcanzar volumen pre-registrado.