Saltar al contenido principal

Evaluaciones de Comportamiento (Behavioral Evals)

El motor de Evaluación de Comportamiento (BehavioralEvaluator) de RAPID OS realiza auditorías offline y deterministas sobre la ejecución de un run. Evalúa el contrato (ExecutionContract), el estado del ciclo (RunState) y el conjunto de evidencias inmutables (RunEvidence[]) contra un conjunto de reglas canónicas (BehavioralRuleset).

Product Truth: La naturaleza de la Evaluación​

Principio de Verdad del Producto:

  1. RAPID OS no invoca modelos LLM para evaluar código ("LLM-as-a-judge"). La evaluación es 100% matemática, lógica y reproducible.
  2. Una declaración de estado (ej. GateDisposition.ACKNOWLEDGED) es una aserción del usuario; si no cuenta con evidencia observable respaldándola, el evaluador la marca como UNVERIFIED.
  3. El veredicto PASS certifica que las reglas y compuertas exigidas por la política se satisfacen con las evidencias registradas. No garantiza matemáticamente que el software esté libre de defectos.

1. Los cuatro veredictos de Evaluación (EvaluationVerdict)​

VeredictoSignificadoExigencia en CI (--require-pass)
passTodas las compuertas obligatorias y requerimientos cuentan con evidencias válidas que las satisfacen al 100%.Pasa (Exit code 0)
pass_with_waiversTodas las compuertas se satisfacen, pero una o más compuertas permitidas fueron formalmente exentas con un waiver justificado.Pasa (Exit code 0)
unverifiedExisten compuertas reconocidas en el estado que carecen del registro de evidencia observable correspondiente.Falla (Exit code 1, diagnóstico RAPID1225)
failAl menos una compuerta obligatoria fue rechazada, omitida, o una prueba falló según la evidencia registrada.Falla (Exit code 1, diagnóstico RAPID1226)

2. Ejecución de la Evaluación (rapid eval run)​

Por defecto, la evaluación se ejecuta en modo de solo lectura para inspeccionar el resultado en terminal:

# Evaluación en memoria (Read-only)
rapid eval run --run my-run-001

# Evaluación con formato JSON
rapid eval run --run my-run-001 --json

Persistir el reporte de evaluación (--write)​

Para registrar el reporte inmutable en .rapid-os/evals/<run-id>/reports/eval_report_0001.json:

rapid eval run --run my-run-001 --write

Modo estricto para integración continua (--require-pass)​

En flujos de CI/CD o hooks pre-merge, puedes exigir que el comando falle si el veredicto no es pass o pass_with_waivers:

rapid eval run --run my-run-001 --require-pass

3. Inspección y Repetición Semántica (Replay)​

RAPID OS permite consultar el histórico de reportes de evaluación generados para un run:

# Listar reportes generados
rapid eval list --run my-run-001

# Inspeccionar el detalle de una revisión de reporte
rapid eval show --run my-run-001 --revision 1

Protección contra manipulación manual​

Cada vez que se carga un reporte (rapid eval show o rapid validate), RAPID OS ejecuta una repetición semántica obligatoria (semantic replay): vuelve a computar las aserciones sobre el contrato, el estado y las evidencias reales en disco. Si alguien alteró manualmente el archivo de reporte para cambiar un FAIL por PASS, el sistema detecta la discrepancia y emite el diagnóstico RAPID1223.

4. Estructura de un Reporte de Evaluación (EvaluationReport)​

Un reporte generado contiene los siguientes bloques fundamentales:

{
  "schema_version": 1,
  "run_id": "my-run-001",
  "revision": 1,
  "verdict": "pass",
  "ruleset_version": 1,
  "ruleset_digest": "3a4b5c6d...",
  "contract_digest": "e1f2a3b4...",
  "state_digest": "9f8e7d6c...",
  "evidence_set_digest": "4c3b2a1f...",
  "summary": {
    "total_assertions": 8,
    "satisfied": 8,
    "waived": 0,
    "unverified": 0,
    "failed": 0
  },
  "assertions": [
    {
      "id": "A001_contract_integrity",
      "category": "contract",
      "status": "satisfied",
      "target": "ExecutionContract",
      "reason": "Digest coincide y spec está en estado ready"
    },
    {
      "id": "A002_gate_implementation_tests",
      "category": "gate",
      "status": "satisfied",
      "target": "implementation_tests",
      "reason": "Evidencia E001 (test_result) acredita 42 tests exitosos"
    }
  ]
}

5. Versiones de Ruleset: Comparativa v1 vs v2​

A partir de Rapid OS v3.2, el motor de evaluación soporta múltiples versiones de reglas (BehavioralRuleset):

CaracterísticaRuleset v1Ruleset v2
Versión por defectoCompatible con runs históricosRegla activa por defecto en rapid eval run
Compuertas Humanas (GateKind)Aceptaba revisiones emitidas por cualquier productor (incluyendo harness:*)Rechaza productores harness:* para compuertas de revisión humana (peer_review, security_review, migration_review, manual_approval, final_verification). Quedan UNVERIFIED si las firma un harness
Compuertas Automáticas / MachineAcepta harness:* y herramientasAcepta harness:* y herramientas
Fallas Esperadas (expectation: "fail")Evaluadas como fallas regularesSoportadas para verificación de reproducción de defectos (TDD/Bugfix); el evaluador produce aserciones reproduction.<task-id>
CLI --ruleset--ruleset 1--ruleset 2 (por defecto en los runs creados antes del ruleset 3)

Ruleset v3 (por defecto en los runs nuevos)​

Todo run creado con Rapid OS 3.2 registra ruleset_version: 3 en su contrato y se evalúa con él; un run cuyo contrato no tiene ruleset_version se creó con una versión anterior y conserva el ruleset 2. El ruleset 3 cambia tres reglas:

ReglaRuleset v2Ruleset v3
Gates de tests (gate.tests, gate.baseline)Un test_result que pasa (y, para la baseline, un command_result) con un log como artefacto, de cualquier productorSolo evidencia producida por rapid:check, con counted: true (la salida tenía un resumen de tests) o test_command: true (el argv era exactamente test_command), al menos un test ejecutado cuando hay conteo y un tree registrado. Cualquier otra cosa es UNVERIFIED (RAPID1432), nunca PASS; la evidencia que falla sigue siendo FAIL
Gates humanosUn review aprobado de user, ci:* o external:*Solo un review aprobado escrito por rapid approve (producer user, via: rapid:approve); rapid evidence add no puede escribirlo (RAPID1430) y rapid run gate no puede reconocer un gate humano (RAPID1431)
Fallar cerradoUna evidencia de tests sin tree no se juzgarapid next, rapid approve y rapid finish la tratan como código no verificado (RAPID1434); rapid finish además rechaza el código que cambió después de la aprobación (RAPID1433) y un comando de tests distinto al de la baseline salvo que la persona lo acepte (RAPID1435)

rapid eval run --ruleset 3 evalúa cualquier run con él.

[!IMPORTANT] Los reportes guardados con --write registran su ruleset_version. Al ejecutar rapid eval show o rapid validate, el replay semántico utiliza exactamente la versión declarada en el reporte para garantizar reproducibilidad histórica inmutable.