santismm-knowledge-mcp 0.2.1

package/content/harness/HRN-007-evaluation-of-agentic-systems.es.md

@@ -0,0 +1,96 @@
+---
+title: "Evaluación de sistemas agénticos"
+summary: "Cómo pasar de «parece que funciona» a calidad medida y protegida frente a regresiones: conjuntos de evaluación, jueces, métricas de tarea y evaluación continua en producción."
+---
+
+# Evaluación de sistemas agénticos
+
+## Resumen ejecutivo
+La evaluación es el componente del harness que convierte «parece que funciona» en una afirmación medida y defendible. Como los agentes no son deterministas y operan sobre tareas abiertas, no se llega a la confianza a base de aserciones: hay que medir distribuciones de comportamiento contra referencias conocidas y protegerse frente a regresiones. Este capítulo cubre la evaluación fuera de línea y en línea, los conjuntos de referencia, el LLM como juez, las suites de regresión y las métricas de finalización de tarea, y sostiene que la evaluación es la línea que separa el *oficio* de agentes de la *ingeniería* de agentes.
+
+## Conceptos clave
+- **Evaluación fuera de línea:** puntuar al agente contra un conjunto de datos fijo antes de desplegar.
+- **Evaluación en línea:** puntuar tráfico de producción real (con señales de usuario o jueces en sombra).
+- **Conjunto de referencia (golden set):** un conjunto curado de entradas con salidas esperadas conocidas o criterios de aceptación.
+- **LLM como juez:** usar un modelo para puntuar salidas contra una rúbrica cuando la coincidencia exacta es imposible.
+- **Suite de regresión:** un conjunto de casos que se ejecuta en cada cambio para cazar caídas de calidad.
+- **Tasa de finalización de tarea:** la proporción de intentos que alcanzan el objetivo de principio a fin.
+- **Evaluación de trayectoria:** puntuar el *camino* que tomó el agente, no solo su respuesta final.
+
+## Definición
+La **evaluación de un sistema agéntico** es el subsistema del harness que mide la calidad, la seguridad y la fiabilidad del comportamiento del agente contra criterios definidos —sobre conjuntos curados (fuera de línea) y sobre tráfico real (en línea)— y condiciona los cambios al resultado. Responde a dos preguntas: «¿es suficientemente bueno para salir?» y «¿este cambio lo ha mejorado o empeorado?».
+
+## Explicación detallada
+
+### Por qué evaluar agentes es difícil
+Tres propiedades lo hacen más duro que probar software tradicional. Primera, el **no determinismo**: la misma entrada puede dar salidas distintas e incluso *caminos* distintos, así que una única aserción de pasa/falla no significa nada; se miden tasas sobre ejecuciones. Segunda, la **apertura**: existen muchas respuestas correctas, así que la puntuación por coincidencia exacta falla y hace falta juicio por rúbrica o semántico. Tercera, las **trayectorias de varios pasos**: un agente puede llegar a la respuesta correcta por un camino equivocado (inseguro, caro), así que evaluar solo la salida final es insuficiente. El diseño de evaluación es el arte de convertir esas propiedades en señales medibles.
+
+### Evaluación fuera de línea y conjuntos de referencia
+La evaluación fuera de línea ejecuta el agente sobre un **conjunto de referencia** —entradas curadas emparejadas con salidas esperadas o criterios de aceptación— antes de que nada salga a producción. El conjunto de referencia es el activo más valioso que produce la evaluación: codifica qué significa «bueno» en tu dominio y se acumula con el tiempo. Constrúyelo a partir de casos reales (anonimizados) de producción, casos de fallo conocidos y casos límite, y *hazlo crecer con cada incidente*: cuando el agente falla en producción, el arreglo no es solo un cambio de código sino un caso de referencia nuevo, para que ese fallo no pueda volver en silencio. Esa es la disciplina de regresión (conocimiento del tipo PAT-015, validación de conocimiento) que hace mejorable el sistema.
+
+### Tipos de evaluador: cada método a su tarea
+- **Evaluadores exactos o por reglas** para tareas con salida verificable (un resultado SQL correcto, un esquema JSON válido, un test unitario que pasa). Baratos, deterministas, de fiar: úsalos siempre que puedas.
+- **LLM como juez** para salidas abiertas donde la coincidencia exacta falla (resúmenes, explicaciones, planes). Un modelo puntúa contra una rúbrica. Potente pero falible: los jueces tienen sesgos (posición, verbosidad, preferencia por sí mismos), así que calíbralos contra etiquetas humanas, usa rúbricas claras y prefiere la comparación por pares a la puntuación absoluta cuando sea posible. Trata al juez como *un instrumento que a su vez necesita evaluación*.
+- **Revisión humana** para los casos de mayor riesgo o más ambiguos, y para calibrar los evaluadores automáticos. Es cara, así que resérvala para los casos que la necesitan y para mantener honestos a los evaluadores baratos.
+
+### Métricas de finalización y de trayectoria
+La métrica de cabecera de un agente suele ser la **tasa de finalización de tarea**: de principio a fin, ¿alcanzó el objetivo? Por debajo viven métricas de paso y de trayectoria: ¿eligió herramientas adecuadas, evitó pasos innecesarios, se mantuvo en presupuesto y evitó acciones inseguras por el camino? La evaluación de trayectoria caza a los agentes que aciertan «por las razones equivocadas», que es precisamente el tipo de fragilidad que se rompe ante un cambio de distribución. Empareja la tasa de finalización con el coste por tarea y la tasa de violaciones de seguridad para no optimizar una a costa de las otras.
+
+### Evaluación en línea
+La evaluación fuera de línea te habla de tu conjunto de datos; solo la **evaluación en línea** te habla de la realidad. La evaluación en línea puntúa tráfico vivo usando señales implícitas de usuario (aceptación, ediciones, escalados, reintentos), jueces LLM en sombra corriendo sobre trazas de producción (HRN-006) y auditorías humanas periódicas de ejecuciones muestreadas. La evaluación en línea es además la forma de descubrir casos de referencia nuevos: producción es la fuente más rica de los casos límite que le faltan a tu conjunto fuera de línea. El bucle es: observar (HRN-006) → juzgar en línea → cosechar los fallos hacia el conjunto de referencia → proteger con regresión fuera de línea.
+
+### Puertas de regresión: la evaluación como puerta de CI
+La disciplina se vuelve ingeniería cuando la evaluación *condiciona los cambios*. Cada edición de prompt, cambio de modelo o cambio de herramienta se ejecuta contra la suite de regresión, y una caída de calidad bloquea el merge, exactamente igual que un test unitario en rojo bloquea el código. Es la forma operativa del principio de evidencia primero (HRN-004): nada sale a producción por intuición. Como la evaluación de agentes se basa en tasas y en parte la juzga un LLM, las puertas usan umbrales y comparación estadística en lugar de un único booleano, pero el principio es idéntico.
+
+## Evidencia de producción
+> **Nivel de evidencia:** teórico · **Confianza:** media · **Fuente:** observación de industria
+>
+> _Escenario ilustrativo y representativo, no un despliegue verificado concreto._
+
+- **Contexto:** equipos que iteran sobre un agente en producción cambiando prompts con frecuencia e intercambiando modelos.
+- **Escenario:** sin puerta de evaluación, un cambio de prompt que mejoraba un caso empeoró en silencio varios otros y sacó a producción un agente peor en neto; introducir una suite de regresión sobre conjunto de referencia con LLM como juez más evaluadores por reglas cazó la regresión antes del despliegue.
+- **Tecnología:** harness de conjunto de referencia, evaluadores por reglas y LLM como juez, puerta de CI, juez en línea sobre trazas de producción.
+- **Carga:** cambios frecuentes contra un conjunto de referencia que va de decenas a miles de casos.
+- **Resultados:** la experiencia representativa es que la calidad deja de derivar en cuanto los cambios pasan por la puerta, y que el conjunto de referencia —crecido continuamente a partir de fallos de producción— se convierte en el activo más valioso del equipo.
+
+## Modos de fallo observados
+- **Salir a producción por intuición:** cambios evaluados probando a ojo unos pocos prompts, de modo que las regresiones salen sin que nadie se entere.
+- **Sobreajuste al conjunto de referencia:** afinar hasta que el conjunto fijo pasa mientras la calidad real se estanca; se mitiga haciendo crecer el conjunto con casos frescos de producción.
+- **LLM como juez ingenuo:** confiar en un juez sin calibrar con sesgos conocidos; tratar sus puntuaciones como verdad de campo sin validación humana.
+- **Puntuar solo la respuesta final:** se escapan los agentes que llegan a respuestas correctas por caminos inseguros o caros.
+- **Sin evaluación en línea:** números fuera de línea excelentes que no sobreviven al contacto con tráfico real y cambiante.
+
+## KPIs
+| Métrica | Objetivo | Notas |
+|---------|----------|-------|
+| Tasa de finalización de tarea | Dependiente del dominio, con tendencia | Métrica de calidad principal |
+| Tasa de aprobación de la suite de regresión | 100 % antes de desplegar | Puerta en cada cambio |
+| Concordancia juez–humano | Alta, calibrada | Valida el instrumento «LLM como juez» |
+| Tasa de violaciones de seguridad | Cercana a cero | A nivel de trayectoria, no solo de respuesta final |
+| Coste por tarea exitosa | Minimizado | Se empareja con la finalización para evitar sobreoptimizar |
+
+## Métricas de coste
+La evaluación añade coste en tres sitios: ejecutar el agente sobre el conjunto de referencia (inferencia), la puntuación con LLM como juez (más inferencia) y la revisión humana (trabajo). Se controlan por niveles: primero los evaluadores por reglas, baratos; el juez LLM para el subconjunto abierto; los humanos para calibrar y para los casos de mayor riesgo. El coste se devuelve evitando regresiones, que son mucho más caras una vez desplegadas. Reutilizar las trazas de observabilidad (HRN-006) para reproducción fuera de línea evita volver a ejecutar el modelo donde sea posible.
+
+## Características de escalado
+El coste de evaluación escala con tamaño del conjunto × coste del evaluador × frecuencia de cambio. A medida que el conjunto crece, el muestreo y la puntuación por niveles mantienen asequibles las ejecuciones de regresión; los casos más informativos pueden ponderarse o ejecutarse más a menudo. La evaluación en línea escala con el tráfico muestreado y no con todo él. El propio conjunto de referencia escala *hacia arriba* en valor a medida que crece —lo contrario que la mayoría de las curvas de coste— porque cada caso añadido es un modo de fallo protegido para siempre.
+
+## Contenido relacionado
+- HRN-006 — Observabilidad para sistemas agénticos
+- PAT-009 — (patrón de evaluación / juicio)
+- PAT-015 — Validación de conocimiento
+
+## Referencias
+- Literatura de práctica sobre evaluación de LLM, calibración del LLM como juez y conjuntos de referencia.
+- Observación de industria sobre puertas de regresión para sistemas agénticos, 2023–2026.
+- Santa María, S. — Notas de trabajo sobre la disciplina de evaluación de agentes.
+
+## Preguntas frecuentes
+**P:** ¿Puedo fiarme sin más de un LLM como juez?
+**R:** Úsalo, pero trátalo como un instrumento que a su vez necesita evaluación. Calíbralo contra etiquetas humanas, dale rúbricas explícitas, prefiere la comparación por pares y vigila los sesgos conocidos (posición, verbosidad, preferencia por sí mismo).
+
+**P:** ¿De dónde salen los casos de referencia?
+**R:** De tráfico de producción real (anonimizado), de casos de fallo conocidos y de casos límite; y, sobre todo, cada incidente de producción debería añadir un caso de referencia nuevo para que ese fallo no pueda repetirse en silencio.
+
+**P:** Evaluación fuera de línea o en línea, ¿cuál necesito?
+**R:** Ambas. La de fuera de línea condiciona los cambios antes de desplegar contra un conjunto conocido; la de en línea te dice qué está pasando de verdad y realimenta casos nuevos hacia el conjunto fuera de línea. Forman un bucle con la observabilidad.

package/content/harness/HRN-007-evaluation-of-agentic-systems.md

@@ -0,0 +1,145 @@
+---
+id: HRN-007
+title: Evaluation of Agentic Systems
+domain: Harness
+category: Evaluation
+status: Draft
+author: Santiago Santa María
+created: 2026-06-21
+updated: 2026-06-21
+summary: How to measure whether an agent is actually good and getting better — offline and online evaluation, golden sets, LLM-as-judge, regression suites, and task-completion metrics — turning agent development from craft into engineering.
+evidence_level: theoretical
+confidence_level: medium
+source_type:
+  - industry_observation
+  - personal_experience
+related:
+  - HRN-006
+  - PAT-009
+  - PAT-015
+tags:
+  - evaluation
+  - llm-as-judge
+  - golden-set
+  - regression
+  - task-completion
+---
+
+# Evaluation of Agentic Systems
+
+## Executive Summary
+Evaluation is the harness component that converts "it seems to work" into a measured, defensible claim. Because agents are non-deterministic and operate over open-ended tasks, you cannot assert your way to confidence — you must measure distributions of behavior against known-good references and guard against regressions. This chapter covers offline and online evaluation, golden sets, LLM-as-judge, regression suites, and task-completion metrics, and argues that evaluation is the dividing line between agent *craft* and agent *engineering*.
+
+## Key Concepts
+- **Offline evaluation:** Scoring an agent against a fixed dataset before deployment.
+- **Online evaluation:** Scoring live production traffic (with user signals or shadow judges).
+- **Golden set:** A curated dataset of inputs with known-good expected outputs or acceptance criteria.
+- **LLM-as-judge:** Using a model to score outputs against a rubric where exact-match is impossible.
+- **Regression suite:** A set of cases run on every change to catch quality drops.
+- **Task-completion rate:** The share of attempts that achieve the goal end-to-end.
+- **Trajectory evaluation:** Scoring the *path* an agent took, not only its final answer.
+
+## Definition
+**Evaluation of an agentic system** is the harness subsystem that measures the quality, safety, and reliability of agent behavior against defined criteria — across curated datasets (offline) and live traffic (online) — and gates changes on the results. It answers two questions: "is it good enough to ship?" and "did this change make it better or worse?"
+
+## Architecture Diagram
+```mermaid
+flowchart TB
+  subgraph OFFLINE["Offline Evaluation (pre-deploy)"]
+    GOLD[(Golden Set)] --> RUNO[Run Agent]
+    RUNO --> SCORE1[Scorers]
+    SCORE1 --> GATE{Regression Gate}
+    GATE -->|pass| SHIP[Deploy]
+    GATE -->|fail| BLOCK[Block / Investigate]
+  end
+  subgraph ONLINE["Online Evaluation (live)"]
+    PROD[Production Traffic] --> TRACE[Traces HRN-006]
+    TRACE --> JUDGE[LLM-as-Judge / Rules]
+    PROD --> USERSIG[User Signals]
+    JUDGE --> MON[Monitors & Dashboards]
+    USERSIG --> MON
+  end
+  subgraph SCORERS["Scorer Types"]
+    EXACT[Exact / Rule-based]
+    LLMJ[LLM-as-Judge]
+    HUMAN[Human Review]
+  end
+  SCORE1 --- SCORERS
+  JUDGE --- SCORERS
+  MON -.feeds new cases.-> GOLD
+```
+
+## Detailed Explanation
+
+### Why agent evaluation is hard
+Three properties make this harder than traditional software testing. First, **non-determinism**: the same input can yield different outputs and even different *paths*, so a single pass/fail assertion is meaningless — you measure rates over runs. Second, **open-endedness**: many correct answers exist, so exact-match scoring fails and you need rubric-based or semantic judgment. Third, **multi-step trajectories**: an agent can reach a right answer via a wrong (unsafe, expensive) path, so evaluating only the final output is insufficient. Evaluation design is the art of turning these properties into measurable signals.
+
+### Offline evaluation and golden sets
+Offline evaluation runs the agent over a fixed **golden set** — curated inputs paired with expected outputs or acceptance criteria — before anything ships. The golden set is the most valuable asset evaluation produces; it encodes what "good" means for your domain and compounds over time. Build it from real (anonymized) production cases, known failure cases, and edge cases, and *grow it from every incident*: when the agent fails in production, the fix is not just a code change but a new golden case so the failure can never silently return. This is the regression discipline (PAT-015-class knowledge validation) that makes the system improvable.
+
+### Scorer types — matching the method to the task
+- **Exact / rule-based scorers** for tasks with verifiable outputs (a correct SQL result, a valid JSON schema, a passing unit test). Cheap, deterministic, trustworthy — use them wherever possible.
+- **LLM-as-judge** for open-ended outputs where exact-match fails (summaries, explanations, plans). A model scores against a rubric. Powerful but fallible: judges have biases (position, verbosity, self-preference), so calibrate them against human labels, use clear rubrics, and prefer pairwise comparison over absolute scoring where feasible. Treat the judge as an *instrument that itself needs evaluation*.
+- **Human review** for the highest-stakes or most-ambiguous cases, and to calibrate the automated scorers. Expensive, so reserve it for the cases that need it and for keeping the cheaper scorers honest.
+
+### Task-completion and trajectory metrics
+The headline metric for an agent is usually **task-completion rate**: end-to-end, did it achieve the goal? Beneath it sit step-level and trajectory metrics — did it choose appropriate tools, avoid unnecessary steps, stay in budget, and avoid unsafe actions along the way? Trajectory evaluation catches agents that are "right for the wrong reasons," which is precisely the kind of fragility that breaks under distribution shift. Pair completion rate with cost-per-task and safety-violation rate to avoid optimizing one at the expense of the others.
+
+### Online evaluation
+Offline tells you about your dataset; only **online evaluation** tells you about reality. Online evaluation scores live traffic using implicit user signals (acceptance, edits, escalations, retries), shadow LLM-judges running on production traces (HRN-006), and periodic human audits of sampled runs. Online evaluation is also how new golden cases are discovered — production is the richest source of the edge cases your offline set is missing. The loop is: observe (HRN-006) → judge online → harvest failures into the golden set → guard with offline regression.
+
+### Regression gating — evaluation as a CI gate
+The discipline becomes engineering when evaluation *gates changes*. Every prompt edit, model swap, or tool change runs against the regression suite, and a quality drop blocks the merge — exactly as a failing unit test blocks code. This is the operational form of the evidence-first principle (HRN-004): no change ships on vibes. Because agent evaluation is rate-based and partly LLM-judged, gates use thresholds and statistical comparison rather than a single boolean, but the principle is identical.
+
+## Production Evidence
+> **Evidence level:** theoretical · **Confidence:** medium · **Source:** industry_observation
+>
+> _Illustrative, representative scenario — not a verified single deployment._
+
+- **Context:** Teams iterating on a production agent by frequently changing prompts and swapping models.
+- **Scenario:** Without an evaluation gate, a prompt change that improved one case silently regressed several others, shipping a net-worse agent; introducing a golden-set regression suite with LLM-as-judge plus rule-based scorers caught the regression before deploy.
+- **Technology:** Golden-set harness, rule-based and LLM-as-judge scorers, CI gate, online judge over production traces.
+- **Load:** Frequent changes against a golden set ranging from dozens to thousands of cases.
+- **Results:** Representative experience is that quality stops drifting once changes are gated, and that the golden set — continuously grown from production failures — becomes the team's most valuable asset.
+
+## Observed Failure Modes
+- **Vibes-based shipping:** Changes evaluated by spot-checking a few prompts, so regressions ship unnoticed.
+- **Overfitting the golden set:** Tuning until the fixed set passes while real-world quality stalls — mitigated by growing the set from fresh production cases.
+- **Naive LLM-as-judge:** Trusting an uncalibrated judge with known biases; treating its scores as ground truth without validation against humans.
+- **Final-answer-only scoring:** Missing agents that reach right answers via unsafe or expensive paths.
+- **No online evaluation:** Strong offline numbers that do not survive contact with real, shifting traffic.
+
+## KPIs
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Task completion rate | Domain-dependent, trended | Primary headline quality metric |
+| Regression suite pass rate | 100% before deploy | Gate on every change |
+| Judge–human agreement | High, calibrated | Validates the LLM-as-judge instrument |
+| Safety-violation rate | Near zero | Trajectory-level, not just final answer |
+| Cost per successful task | Minimized | Pairs with completion to prevent over-optimization |
+
+## Cost Metrics
+Evaluation adds cost in three places: running the agent over the golden set (inference), LLM-as-judge scoring (more inference), and human review (labor). These are controlled by tiering — cheap rule-based scorers first, LLM-judge for the open-ended subset, humans for calibration and high-stakes cases. The cost is repaid by preventing regressions, which are far more expensive once shipped. Reusing observability traces (HRN-006) for offline replay avoids re-running the model where possible.
+
+## Scaling Characteristics
+Evaluation cost scales with golden-set size × scorer cost × change frequency. As the set grows, sampling and tiered scoring keep regression runs affordable; the most informative cases can be weighted or run more often. Online evaluation scales with sampled traffic rather than all of it. The golden set itself scales *up* in value as it grows — the opposite of most cost curves — because each added case is a permanently guarded failure mode.
+
+## Related Content
+- HRN-006 — Observability for Agentic Systems
+- PAT-009 — (evaluation / judging pattern)
+- PAT-015 — Knowledge Validation
+
+## References
+- Practitioner literature on LLM evaluation, LLM-as-judge calibration, and golden datasets.
+- Industry observation on regression gating for agentic systems, 2023–2026.
+- Santa María, S. — Working notes on agent evaluation discipline.
+
+## FAQs
+**Q:** Can I just trust an LLM-as-judge?
+**A:** Use it, but treat it as an instrument that itself needs evaluation. Calibrate it against human labels, give it explicit rubrics, prefer pairwise comparison, and watch for known biases (position, verbosity, self-preference).
+
+**Q:** Where do golden cases come from?
+**A:** Real (anonymized) production traffic, known failure cases, and edge cases — and crucially, every production incident should add a new golden case so the failure cannot silently recur.
+
+**Q:** Offline or online evaluation — which do I need?
+**A:** Both. Offline gates changes before deploy against a known set; online tells you what is actually happening in reality and feeds new cases back into the offline set. They form a loop with observability.

package/content/harness/HRN-007-evaluation-of-agentic-systems.pt.md

@@ -0,0 +1,96 @@
+---
+title: "Avaliação de sistemas agênticos"
+summary: "Como passar de “parece que funciona” para qualidade medida e protegida contra regressões: conjuntos de avaliação, juízes, métricas de tarefa e avaliação contínua em produção."
+---
+
+# Avaliação de sistemas agênticos
+
+## Resumo executivo
+A avaliação é o componente do harness que converte “parece que funciona” numa afirmação medida e defensável. Como os agentes não são deterministas e operam sobre tarefas abertas, não se chega à confiança à custa de asserções: é preciso medir distribuições de comportamento contra referências conhecidas e proteger-se contra regressões. Este capítulo cobre a avaliação fora de linha e em linha, os conjuntos de referência, o LLM como juiz, as suites de regressão e as métricas de conclusão de tarefa, e sustenta que a avaliação é a linha que separa o *ofício* de agentes da *engenharia* de agentes.
+
+## Conceitos-chave
+- **Avaliação fora de linha:** pontuar o agente contra um conjunto de dados fixo antes de implantar.
+- **Avaliação em linha:** pontuar tráfego de produção real (com sinais de usuário ou juízes em sombra).
+- **Conjunto de referência (golden set):** um conjunto curado de entradas com saídas esperadas conhecidas ou critérios de aceitação.
+- **LLM como juiz:** usar um modelo para pontuar saídas contra uma rubrica quando a correspondência exata é impossível.
+- **Suite de regressão:** um conjunto de casos executado em cada alteração para caçar quedas de qualidade.
+- **Taxa de conclusão de tarefa:** a proporção de tentativas que alcançam o objetivo de ponta a ponta.
+- **Avaliação de trajetória:** pontuar o *caminho* que o agente seguiu, não apenas sua resposta final.
+
+## Definição
+A **avaliação de um sistema agêntico** é o subsistema do harness que mede a qualidade, a segurança e a confiabilidade do comportamento do agente contra critérios definidos — sobre conjuntos curados (fora de linha) e sobre tráfego real (em linha) — e condiciona as alterações ao resultado. Responde a duas perguntas: “é suficientemente bom para sair?” e “esta alteração melhorou-o ou piorou-o?”.
+
+## Explicação detalhada
+
+### Por que avaliar agentes é difícil
+Três propriedades tornam isto mais duro do que testar software tradicional. Primeira, o **não determinismo**: a mesma entrada pode dar saídas diferentes e até *caminhos* diferentes, portanto uma única asserção de passa/falha não significa nada; medem-se taxas sobre execuções. Segunda, a **abertura**: existem muitas respostas corretas, portanto a pontuação por correspondência exata falha e é preciso juízo por rubrica ou semântico. Terceira, as **trajetórias de vários passos**: um agente pode chegar à resposta certa por um caminho errado (inseguro, caro), portanto avaliar apenas a saída final é insuficiente. O desenho de avaliação é a arte de converter essas propriedades em sinais mensuráveis.
+
+### Avaliação fora de linha e conjuntos de referência
+A avaliação fora de linha executa o agente sobre um **conjunto de referência** — entradas curadas emparelhadas com saídas esperadas ou critérios de aceitação — antes de seja o que for entrar em produção. O conjunto de referência é o ativo mais valioso que a avaliação produz: codifica o que significa “bom” no seu domínio e acumula-se ao longo do tempo. Construa-o a partir de casos reais (anonimizados) de produção, casos de falha conhecidos e casos-limite, e *faça-o crescer com cada incidente*: quando o agente falha em produção, a correção não é apenas uma alteração de código mas um novo caso de referência, para que essa falha não possa voltar em silêncio. É essa a disciplina de regressão (conhecimento do tipo PAT-015, validação de conhecimento) que torna o sistema melhorável.
+
+### Tipos de avaliador: cada método à sua tarefa
+- **Avaliadores exatos ou por regras** para tarefas com saída verificável (um resultado SQL correto, um esquema JSON válido, um teste unitário que passa). Baratos, deterministas, de confiança: use-os sempre que puder.
+- **LLM como juiz** para saídas abertas onde a correspondência exata falha (resumos, explicações, planos). Um modelo pontua contra uma rubrica. Poderoso mas falível: os juízes têm enviesamentos (posição, verbosidade, preferência por si próprios), portanto deve calibrá-los contra etiquetas humanas, usar rubricas claras e preferir a comparação aos pares à pontuação absoluta sempre que possível. Trate o juiz como *um instrumento que por sua vez precisa de avaliação*.
+- **Revisão humana** para os casos de maior risco ou mais ambíguos, e para calibrar os avaliadores automáticos. É cara, por isso reserve-a para os casos que dela precisam e para manter honestos os avaliadores baratos.
+
+### Métricas de conclusão e de trajetória
+A métrica de cabeçalho de um agente costuma ser a **taxa de conclusão de tarefa**: de ponta a ponta, alcançou o objetivo? Por baixo vivem métricas de passo e de trajetória: escolheu ferramentas adequadas, evitou passos desnecessários, manteve-se dentro do orçamento e evitou ações inseguras pelo caminho? A avaliação de trajetória caça os agentes que acertam “pelas razões erradas”, que é precisamente o tipo de fragilidade que se quebra perante uma mudança de distribuição. Emparelhe a taxa de conclusão com o custo por tarefa e a taxa de violações de segurança para não otimizar uma à custa das outras.
+
+### Avaliação em linha
+A avaliação fora de linha lhe fala do seu conjunto de dados; só a **avaliação em linha** lhe fala da realidade. A avaliação em linha pontua tráfego vivo usando sinais implícitos do usuário (aceitação, edições, escalonamentos, repetições), juízes LLM em sombra rodando sobre traços de produção (HRN-006) e auditorias humanas periódicas de execuções amostradas. A avaliação em linha é ainda a forma de descobrir novos casos de referência: a produção é a fonte mais rica dos casos-limite que faltam ao seu conjunto fora de linha. O ciclo é: observar (HRN-006) → julgar em linha → colher as falhas para o conjunto de referência → proteger com regressão fora de linha.
+
+### Portas de regressão: a avaliação como porta de CI
+A disciplina se torna engenharia quando a avaliação *condiciona as alterações*. Cada edição de prompt, troca de modelo ou alteração de ferramenta é executada contra a suite de regressão, e uma queda de qualidade bloqueia o merge, exatamente como um teste unitário em falha bloqueia o código. É a forma operacional do princípio de evidência primeiro (HRN-004): nada entra em produção por intuição. Como a avaliação de agentes se baseia em taxas e é em parte julgada por um LLM, as portas usam limiares e comparação estatística em vez de um único booleano, mas o princípio é idêntico.
+
+## Evidência de produção
+> **Nível de evidência:** teórico · **Confiança:** média · **Fonte:** observação de indústria
+>
+> _Cenário ilustrativo e representativo, não uma implantação verificada concreta._
+
+- **Contexto:** equipes que iteram sobre um agente em produção alterando prompts com frequência e trocando de modelos.
+- **Cenário:** sem porta de avaliação, uma alteração de prompt que melhorava um caso piorou em silêncio vários outros e colocou em produção um agente pior no total; introduzir uma suite de regressão sobre conjunto de referência com LLM como juiz mais avaliadores por regras caçou a regressão antes da implantação.
+- **Tecnologia:** harness de conjunto de referência, avaliadores por regras e LLM como juiz, porta de CI, juiz em linha sobre traços de produção.
+- **Carga:** alterações frequentes contra um conjunto de referência que vai de dezenas a milhares de casos.
+- **Resultados:** a experiência representativa é que a qualidade deixa de derivar assim que as alterações passam pela porta, e que o conjunto de referência — crescido continuamente a partir de falhas de produção — se torna o ativo mais valioso da equipe.
+
+## Modos de falha observados
+- **Entrar em produção por intuição:** alterações avaliadas testando a olho uns poucos prompts, de modo que as regressões saem sem ninguém dar conta.
+- **Sobreajuste ao conjunto de referência:** afinar até o conjunto fixo passar enquanto a qualidade real estagna; mitiga-se fazendo crescer o conjunto com casos frescos de produção.
+- **LLM como juiz ingênuo:** confiar num juiz não calibrado com enviesamentos conhecidos; tratar suas pontuações como verdade de campo sem validação humana.
+- **Pontuar apenas a resposta final:** escapam os agentes que chegam a respostas corretas por caminhos inseguros ou caros.
+- **Sem avaliação em linha:** números fora de linha excelentes que não sobrevivem ao contato com tráfego real e mutável.
+
+## KPIs
+| Métrica | Objetivo | Notas |
+|---------|----------|-------|
+| Taxa de conclusão de tarefa | Dependente do domínio, com tendência | Métrica de qualidade principal |
+| Taxa de aprovação da suite de regressão | 100 % antes de implantar | Porta em cada alteração |
+| Concordância juiz–humano | Alta, calibrada | Valida o instrumento “LLM como juiz” |
+| Taxa de violações de segurança | Perto de zero | Ao nível da trajetória, não só da resposta final |
+| Custo por tarefa bem-sucedida | Minimizado | Emparelha com a conclusão para evitar sobre-otimizar |
+
+## Métricas de custo
+A avaliação acrescenta custo em três pontos: executar o agente sobre o conjunto de referência (inferência), a pontuação com LLM como juiz (mais inferência) e a revisão humana (trabalho). Controlam-se por níveis: primeiro os avaliadores por regras, baratos; o juiz LLM para o subconjunto aberto; os humanos para calibrar e para os casos de maior risco. O custo é devolvido evitando regressões, que são muito mais caras depois de implantadas. Reutilizar os traços de observabilidade (HRN-006) para reprodução fora de linha evita voltar a executar o modelo onde for possível.
+
+## Características de escalabilidade
+O custo de avaliação escala com dimensão do conjunto × custo do avaliador × frequência de alteração. À medida que o conjunto cresce, a amostragem e a pontuação por níveis mantêm acessíveis as execuções de regressão; os casos mais informativos podem ser ponderados ou executados mais vezes. A avaliação em linha escala com o tráfego amostrado e não com a totalidade. O próprio conjunto de referência escala *para cima* em valor à medida que cresce — o contrário da maioria das curvas de custo — porque cada caso acrescentado é um modo de falha protegido para sempre.
+
+## Conteúdo relacionado
+- HRN-006 — Observabilidade para sistemas agênticos
+- PAT-009 — (padrão de avaliação / julgamento)
+- PAT-015 — Validação de conhecimento
+
+## Referências
+- Literatura de prática sobre avaliação de LLM, calibração do LLM como juiz e conjuntos de referência.
+- Observação de indústria sobre portas de regressão para sistemas agênticos, 2023–2026.
+- Santa María, S. — Notas de trabalho sobre a disciplina de avaliação de agentes.
+
+## Perguntas frequentes
+**P:** Posso simplesmente confiar num LLM como juiz?
+**R:** Use-o, mas trate-o como um instrumento que por sua vez precisa de avaliação. Calibre-o contra etiquetas humanas, dê-lhe rubricas explícitas, prefira a comparação aos pares e vigie os enviesamentos conhecidos (posição, verbosidade, preferência por si próprio).
+
+**P:** De onde vêm os casos de referência?
+**R:** De tráfego de produção real (anonimizado), de casos de falha conhecidos e de casos-limite; e, sobretudo, cada incidente de produção deveria acrescentar um novo caso de referência para que essa falha não se possa repetir em silêncio.
+
+**P:** Avaliação fora de linha ou em linha, qual preciso?
+**R:** Ambas. A de fora de linha condiciona as alterações antes de implantar contra um conjunto conhecido; a de em linha diz o que está realmente acontecendo e realimenta novos casos para o conjunto fora de linha. Formam um ciclo com a observabilidade.

package/content/harness/HRN-008-governance-within-the-harness.es.md

@@ -0,0 +1,105 @@
+---
+title: "Gobernanza dentro del harness"
+summary: "Traducir la política en controles aplicados: aprobaciones humanas, trazabilidad, identidad del agente y rendición de cuentas exigibles en un entorno regulado."
+---
+
+# Gobernanza dentro del harness
+
+## Resumen ejecutivo
+
+La gobernanza no es un documento que vive en un wiki: en un sistema agéntico fiable es una **capa de ejecución del harness**. Este capítulo sostiene que las obligaciones de IA empresarial (regulatorias, contractuales y basadas en riesgo) deben compilarse en controles ejecutables situados en el camino crítico entre la intención del modelo y la acción del sistema. La Ingeniería de Harness trata la gobernanza como código: puntos de decisión de política, puertas de aprobación y guardarraíles que observan, permiten, transforman o bloquean cada llamada a herramienta. Sin esa capa, la autonomía de un agente está sin gobernar por construcción; con ella, la autonomía se vuelve acotada, auditable y defendible.
+
+## Conceptos clave
+
+- **Punto de aplicación de política (PEP):** el componente del harness que intercepta una acción del agente y consulta una decisión.
+- **Punto de decisión de política (PDP):** el motor que evalúa la política contra el contexto de la acción y devuelve permitir, denegar o transformar.
+- **Guardarraíl:** una comprobación en ejecución sobre entradas o salidas (contenido, esquema, datos personales, jurisdicción) que restringe el comportamiento.
+- **Puerta de aprobación:** un control que suspende la ejecución a la espera de una decisión humana o de una autoridad superior (véase PAT-001).
+- **Política como código:** reglas de gobernanza expresadas en un formato declarativo, versionado y comprobable.
+- **Rastro de auditoría:** el registro inmutable de qué se intentó, qué se decidió y por qué.
+
+## Definición
+
+> La **gobernanza dentro del harness** es la disciplina de incorporar la aplicación de políticas, los flujos de aprobación y los guardarraíles como una capa de ejecución de primera clase de un sistema agéntico, de modo que toda acción iniciada por el modelo esté mediada por una decisión explícita y auditable derivada de la política de la empresa.
+
+## Explicación detallada
+
+La capa de gobernanza se estructura en torno a la clásica **separación PEP/PDP** tomada de la arquitectura de autorización (XACML, OPA) y adaptada a agentes no deterministas. El punto de aplicación se teje en el camino de invocación de herramientas del harness, de modo que *ninguna* acción con efecto —enviar un correo, escribir en una base de datos, transferir fondos, llamar a una API externa— llega a un efector sin ser evaluada antes. El punto de decisión evalúa la acción contra un **paquete de políticas**: un conjunto de reglas versionado y comprobable que cubre en nombre de quién actúa el agente, qué clases de datos toca, qué jurisdicciones aplican y qué límites de gasto o de radio de impacto están en vigor.
+
+Más allá del simple permitir/denegar importan tres resultados de aplicación. **Transformar** permite al harness autorizar una acción neutralizando su riesgo: redactar datos personales antes de una llamada saliente, reducir el alcance de una consulta o topar el importe de una transacción. **Escalar** encamina la acción hacia una puerta de aprobación (PAT-001), suspendiendo de forma duradera el plan del agente hasta que decida un humano o un agente supervisor. **Denegar con explicación** devuelve una justificación estructurada al contexto del agente para que el bucle de razonamiento replanifique en lugar de reintentar a ciegas.
+
+Los guardarraíles operan en dos fronteras. Los *guardarraíles de entrada* filtran el contenido recuperado y las instrucciones del usuario en busca de inyección, patrones de jailbreak y peticiones fuera de alcance antes de que influyan en el plan. Los *guardarraíles de salida* validan el contenido generado y los argumentos estructurados de las herramientas contra esquema, política de contenido y reglas de fuga de datos antes de que crucen la frontera de confianza. Y algo esencial: los guardarraíles son **por capas, no únicos**. Un solo clasificador es un único punto de fallo, así que la defensa en profundidad combina comprobaciones deterministas (expresiones regulares, esquema, listas de permitidos), estadísticas (clasificadores) y basadas en modelo (LLM como juez), con valores por defecto conservadores de cierre ante fallo para las acciones de alto riesgo.
+
+La gobernanza define además el **gradiente de autonomía**. El harness asigna a cada clase de acción un modo de control dentro de un espectro: totalmente autónomo, autónomo con registro, humano en el bucle (aprobación requerida) o humano sobre el bucle (el humano puede interrumpir). Ese mapeo es en sí mismo política: un reembolso por debajo de 50 € puede ser autónomo; un reembolso por encima de 5.000 €, o cualquier acción que toque datos regulados, exige una puerta de aprobación. La taxonomía de estos modos de control conecta directamente con la taxonomía del harness (HRN-003) y con el marco de gobernanza empresarial (GOV-001), que aporta las obligaciones que esta capa compila.
+
+Por último, la gobernanza solo es creíble si es **observable y demostrable**. Cada decisión —la acción propuesta, la versión de política consultada, las entradas, el veredicto y la justificación— se escribe en un rastro de auditoría inmutable y consultable. Eso es lo que convierte «tenemos una política de IA» en «podemos demostrar, acción por acción, que la política se aplicó», que es el listón probatorio que reguladores y auditores aplican de verdad.
+
+## Evidencia de producción
+
+> **Escenario ilustrativo y representativo.** Nivel de evidencia: teórico · Confianza: media · Fuente: observación de industria, experiencia personal. Las cifras siguientes son rangos realistas extraídos de patrones observados, no mediciones de un despliegue verificado concreto.
+
+- **Contexto:** un agente de back-office de servicios financieros que redacta y ejecuta remediaciones a clientes.
+- **Escenario:** el agente debe resolver de forma autónoma disputas de importe bajo sin mover nunca fondos por encima de un umbral ni tocar datos de otro cliente.
+- **Tecnología:** orquestador con un PEP en cada llamada a herramienta; paquete de políticas al estilo OPA; guardarraíles de clasificador, esquema y lista de permitidos; cola de aprobación duradera.
+- **Carga:** decenas de miles de acciones al día, con un porcentaje de un solo dígito encaminado a puertas de aprobación.
+- **Resultados (representativos):** en despliegues ilustrativos de esta forma, las capas de gobernanza suelen reducir en un orden de magnitud las violaciones de política de severidad alta frente a una línea base sin gobernar, a cambio de una latencia añadida por acción del orden de decenas bajas de milisegundos para las comprobaciones deterministas, y de una latencia extremo a extremo en las acciones escaladas acotada por el tiempo de respuesta humano.
+
+### Lecciones aprendidas
+
+Los valores por defecto de cierre ante fallo en las clases de acción de alto riesgo no son negociables; los fallos caros vienen de acciones que *nunca se evaluaron* porque se añadió una herramienta nueva sin la política correspondiente. La gobernanza debe por tanto controlar el **registro de herramientas**, no solo su invocación.
+
+## Modos de fallo observados
+
+| Modo de fallo | Disparador | Mitigación |
+|---|---|---|
+| Elusión de política | Herramienta nueva añadida sin gancho PEP | Controlar el registro de herramientas; denegar por defecto lo no mapeado |
+| Evasión de guardarraíl | La inyección de prompt reescribe la intención y pasa un único clasificador | Guardarraíles por capas con cierre ante fallo; comprobaciones de entrada y de salida |
+| Fatiga de aprobación | Puertas demasiado amplias inundan a los humanos, que sellan sin mirar | Puertas por nivel de riesgo; autoaprobar lo de bajo riesgo con registro |
+| Política obsoleta | El paquete de políticas se desalinea de la regulación | Versionar y probar la política como código; revisión periódica de conformidad |
+| Transformación silenciosa | La redacción corrompe una acción legítima | Registrar las transformaciones; devolver la justificación al contexto del agente |
+| Huecos de auditoría | Las decisiones no se persisten antes de ejecutar la acción | Auditoría por escritura anticipada; denegar si el destino de auditoría no está disponible |
+
+## KPIs
+
+| Métrica | Objetivo | Notas |
+|---|---|---|
+| Cobertura de política (clases de acción mapeadas) | 100 % | Sin mapear → denegar por defecto |
+| Tasa de violaciones de severidad alta | → 0 | Por cada 10.000 acciones |
+| Precisión de la puerta de aprobación | Alta | Fracción de escalados que estaban justificados |
+| Latencia de decisión (p95) | < 50 ms en lo determinista | Excluye la espera de aprobación humana |
+| Completitud de auditoría | 100 % | Toda acción con efecto tiene registro de decisión |
+| Tiempo medio de actualización de política | Bajo (horas) | CI/CD de política como código |
+
+## Métricas de coste
+
+- **Sobrecoste de gobernanza por acción:** las comprobaciones deterministas añaden cómputo despreciable; los guardarraíles basados en modelo añaden una o varias llamadas de inferencia auxiliares, que hay que presupuestar dentro del coste por tarea.
+- **Coste de aprobación humana:** el coste variable dominante; se minimiza con una clasificación de riesgo precisa para que solo escale lo que lo merece.
+- **Coste de ingeniería:** redacción de políticas y pruebas de conformidad; se amortiza reutilizando paquetes de políticas entre agentes.
+
+## Características de escalado
+
+La aplicación determinista escala horizontalmente y sin estado junto al orquestador. Los guardarraíles basados en modelo escalan con la capacidad de inferencia y son el cuello de botella de rendimiento con volúmenes altos de acciones: cachéalos y cortocircuítalos antes con comprobaciones deterministas baratas. Las puertas de aprobación escalan con capacidad humana, no con cómputo, así que el objetivo de diseño es mantener la fracción escalada pequeña y estable a medida que crece el volumen de acciones.
+
+## Contenido relacionado
+
+- HRN-003 — Taxonomía de capas del harness y modos de control.
+- GOV-001 — Marco de gobernanza de IA empresarial (las obligaciones que esta capa aplica).
+- PAT-001 — Patrón de aprobación humana (el mecanismo de la puerta de aprobación).
+
+## Referencias
+
+- NIST AI Risk Management Framework (AI RMF 1.0).
+- ISO/IEC 42001:2023 — sistemas de gestión de IA.
+- OASIS XACML y el modelo de autorización PEP/PDP.
+- Open Policy Agent (OPA) — motor de política como código.
+
+## Preguntas frecuentes
+
+**P: ¿Por qué no resolver la gobernanza en el prompt?**
+R: Las instrucciones del prompt son orientativas y derribables por inyección; la aplicación a nivel de harness es obligatoria y auditable. La gobernanza debe quedar fuera de la superficie persuadible del modelo.
+
+**P: ¿No añade demasiada latencia controlar cada acción?**
+R: Las comprobaciones deterministas cuestan entre unos pocos y unas decenas de milisegundos. Solo las acciones escaladas incurren en demora a escala humana, y son deliberadamente raras.
+
+**P: ¿En qué se diferencia esto de GOV-001?**
+R: GOV-001 define las obligaciones y el marco; HRN-008 es cómo esas obligaciones se compilan en controles de ejecución dentro del harness.

package/content/harness/HRN-008-governance-within-the-harness.md

@@ -0,0 +1,146 @@
+---
+id: HRN-008
+title: Governance within the Harness
+domain: Harness
+category: Governance
+status: Draft
+author: Santiago Santa María
+created: 2026-06-21
+updated: 2026-06-21
+summary: Governance is an engineered harness layer that enforces policy, approvals, and guardrails at runtime, turning enterprise AI obligations into executable controls that gate every agent action.
+evidence_level: theoretical
+confidence_level: medium
+source_type:
+  - industry_observation
+  - personal_experience
+related:
+  - HRN-003
+  - GOV-001
+  - PAT-001
+tags:
+  - governance
+  - guardrails
+  - policy-enforcement
+  - approvals
+  - compliance
+---
+
+# Governance within the Harness
+
+## Executive Summary
+
+Governance is not a document that lives in a wiki — in a reliable agentic system it is a **runtime layer of the harness**. This chapter argues that enterprise AI obligations (regulatory, contractual, and risk-based) must be compiled into executable controls that sit on the critical path between the model's intent and the system's action. Harness Engineering treats governance as code: policy decision points, approval gates, and guardrails that observe, allow, transform, or block every tool call. Without this layer, an agent's autonomy is ungoverned by construction; with it, autonomy becomes bounded, auditable, and defensible.
+
+## Key Concepts
+
+- **Policy Enforcement Point (PEP):** the harness component that intercepts an agent action and queries a decision.
+- **Policy Decision Point (PDP):** the engine that evaluates policy against the action's context and returns allow/deny/transform.
+- **Guardrail:** a runtime check on inputs or outputs (content, schema, PII, jurisdiction) that constrains behavior.
+- **Approval gate:** a control that suspends execution pending a human or higher-authority decision (see PAT-001).
+- **Policy-as-code:** governance rules expressed in a declarative, version-controlled, testable format.
+- **Audit trail:** the immutable record of what was attempted, what was decided, and why.
+
+## Definition
+
+> **Governance within the harness** is the discipline of embedding policy enforcement, approval workflows, and guardrails as a first-class runtime layer of an agentic system, such that every model-initiated action is mediated by an explicit, auditable decision derived from enterprise policy.
+
+## Architecture Diagram
+
+```mermaid
+flowchart LR
+    M[Model / Reasoning Loop] -->|proposed action| PEP[Policy Enforcement Point]
+    PEP -->|context + action| PDP[Policy Decision Point]
+    G[(Policy-as-code Bundle)] --> PDP
+    PDP -->|allow| TOOL[Tool / Effector]
+    PDP -->|transform| RW[Redact / Constrain] --> TOOL
+    PDP -->|deny| BLK[Block + Explain]
+    PDP -->|escalate| APR[Approval Gate / Human]
+    APR -->|approved| TOOL
+    APR -->|rejected| BLK
+    PEP --> AUD[(Immutable Audit Log)]
+    PDP --> AUD
+    APR --> AUD
+    TOOL --> AUD
+```
+
+## Detailed Explanation
+
+The governance layer is structured around the classic **PEP/PDP split** borrowed from authorization architecture (XACML, OPA), adapted for non-deterministic agents. The enforcement point is woven into the harness's tool-invocation path so that *no* effectful action — sending an email, writing to a database, transferring funds, calling an external API — reaches an effector without first being evaluated. The decision point evaluates the action against a **policy bundle**: a versioned, testable set of rules covering who the agent acts for, what data classes it touches, which jurisdictions apply, and what spend or blast-radius limits are in force.
+
+Three enforcement outcomes matter beyond simple allow/deny. **Transform** lets the harness permit an action while neutralizing risk — redacting PII before an outbound call, downscoping a query, or capping a transaction amount. **Escalate** routes the action to an approval gate (PAT-001), suspending the agent's plan durably until a human or supervisor agent decides. **Deny-with-explanation** returns a structured rationale into the agent's context so the reasoning loop can replan rather than blindly retry.
+
+Guardrails operate at two boundaries. *Input guardrails* screen retrieved content and user instructions for injection, jailbreak patterns, and out-of-scope requests before they influence the plan. *Output guardrails* validate generated content and structured tool arguments against schema, content policy, and data-loss rules before they leave the trust boundary. Crucially, guardrails are **layered, not singular**: a single classifier is a single point of failure, so defense-in-depth combines deterministic checks (regex, schema, allowlists), statistical checks (classifiers), and model-based checks (LLM-as-judge) with conservative fail-closed defaults for high-risk actions.
+
+Governance also defines the **autonomy gradient**. The harness assigns each action class a control mode along a spectrum: fully autonomous, autonomous-with-logging, human-in-the-loop (approval required), or human-on-the-loop (human can interrupt). This mapping is itself policy: a refund under $50 may be autonomous; a refund over $5,000, or any action touching regulated data, demands an approval gate. The taxonomy of these control modes connects directly to the harness taxonomy (HRN-003) and to the enterprise governance framework (GOV-001), which supplies the obligations this layer compiles.
+
+Finally, governance is only credible if it is **observable and provable**. Every decision — the action proposed, the policy version consulted, the inputs, the verdict, and the rationale — is written to an immutable, queryable audit trail. This is what converts "we have an AI policy" into "we can demonstrate, per action, that policy was enforced," which is the evidentiary bar regulators and auditors actually apply.
+
+## Production Evidence
+
+> **Illustrative / representative scenario.** Evidence level: theoretical · Confidence: medium · Source: industry_observation, personal_experience. The figures below are realistic ranges drawn from observed patterns, not measurements from a single verified deployment.
+
+- **Context:** A financial-services back-office agent that drafts and executes customer remediations.
+- **Scenario:** The agent must autonomously resolve low-value disputes while never autonomously moving funds above a threshold or touching another customer's data.
+- **Technology:** Orchestrator with a PEP on every tool call; OPA-style policy bundle; classifier + schema + allowlist guardrails; durable approval queue.
+- **Load:** Tens of thousands of actions/day; a single-digit percentage routed to approval gates.
+- **Results (representative):** In illustrative deployments of this shape, governance layers commonly reduce high-severity policy violations by an order of magnitude versus an ungoverned baseline, at the cost of added per-action latency in the low tens of milliseconds for deterministic checks and added end-to-end latency for escalated actions bounded by human response time.
+
+### Lessons Learned
+
+Fail-closed defaults on high-risk action classes are non-negotiable; the expensive failures come from actions that were *never evaluated* because a new tool was added without a corresponding policy. Governance must therefore gate **tool registration**, not just tool invocation.
+
+## Observed Failure Modes
+
+| Failure Mode | Trigger | Mitigation |
+|---|---|---|
+| Policy bypass | New tool added without a PEP hook | Gate tool registration; deny-by-default for unmapped actions |
+| Guardrail evasion | Prompt injection rewrites intent past a single classifier | Layered, fail-closed guardrails; input + output checks |
+| Approval fatigue | Over-broad gates flood humans, who rubber-stamp | Risk-tier gates; auto-approve low-risk with logging |
+| Stale policy | Policy bundle drifts from regulation | Version + test policy as code; periodic conformance review |
+| Silent transform | Redaction corrupts a legitimate action | Log transforms; surface rationale into agent context |
+| Audit gaps | Decisions not persisted before action executes | Write-ahead audit; deny if audit sink unavailable |
+
+## KPIs
+
+| Metric | Target | Notes |
+|---|---|---|
+| Policy coverage (action classes mapped) | 100% | Unmapped → deny-by-default |
+| High-severity violation rate | → 0 | Per 10k actions |
+| Approval gate precision | High | Fraction of escalations that were warranted |
+| Decision latency (p95) | < 50 ms deterministic | Excludes human approval wait |
+| Audit completeness | 100% | Every effectful action has a decision record |
+| Mean time to policy update | Low (hours) | Policy-as-code CI/CD |
+
+## Cost Metrics
+
+- **Per-action governance overhead:** deterministic checks add negligible compute; model-based guardrails add one or more auxiliary inference calls — budget for them in cost-per-task.
+- **Human approval cost:** the dominant variable cost; minimized by precise risk-tiering so only warranted actions escalate.
+- **Engineering cost:** policy authoring and conformance testing; amortized as reusable policy bundles across agents.
+
+## Scaling Characteristics
+
+Deterministic enforcement scales horizontally and statelessly with the orchestrator. Model-based guardrails scale with inference capacity and are the throughput bottleneck under high action volume — cache and short-circuit them with cheap deterministic checks first. Approval gates scale with human capacity, not compute, so the design goal is to keep the escalated fraction small and stable as action volume grows.
+
+## Related Content
+
+- HRN-003 — Taxonomy of harness layers and control modes.
+- GOV-001 — Enterprise AI Governance Framework (the obligations this layer enforces).
+- PAT-001 — Human Approval pattern (the approval-gate mechanism).
+
+## References
+
+- NIST AI Risk Management Framework (AI RMF 1.0).
+- ISO/IEC 42001:2023 — AI management systems.
+- OASIS XACML and the PEP/PDP authorization model.
+- Open Policy Agent (OPA) — policy-as-code engine.
+
+## FAQs
+
+**Q: Why not handle governance in the prompt?**
+A: Prompt instructions are advisory and defeasible by injection; harness-level enforcement is mandatory and auditable. Governance must be outside the model's persuadable surface.
+
+**Q: Doesn't gating every action add too much latency?**
+A: Deterministic checks cost single-digit-to-tens of milliseconds. Only escalated actions incur human-scale delay, and those are deliberately rare.
+
+**Q: How is this different from GOV-001?**
+A: GOV-001 defines the obligations and framework; HRN-008 is how those obligations are compiled into runtime controls inside the harness.