santismm-knowledge-mcp 0.2.1

package/content/harness/HRN-011-security-for-agentic-systems.pt.md

@@ -0,0 +1,107 @@
+---
+title: "Segurança para sistemas agênticos"
+summary: "Tratar o modelo como componente não confiável e manipulável: injeção de prompts, exfiltração por ferramentas, limites de autoridade e defesa em profundidade do harness."
+---
+
+# Segurança para sistemas agênticos
+
+## Resumo executivo
+
+Os sistemas agênticos alargam a superfície de ataque de uma forma que as aplicações tradicionais não conhecem: o agente lê dados não confiáveis, toma decisões com consequências e possui privilégios para agir, portanto uma única entrada comprometida pode se tornar uma ação comprometida. A segurança para sistemas agênticos é a camada do harness que assume que o modelo pode ser manipulado — e será — e constrói o andaime circundante para que essa manipulação não possa causar dano. O princípio orientador é **privilégio mínimo com raio de impacto limitado**: tratar o modelo como componente não confiável, colocar os controles de segurança *fora* da sua superfície persuadível e garantir que mesmo um agente completamente sequestrado só possa causar um dano limitado e auditável.
+
+## Conceitos-chave
+
+- **Injeção de prompt:** conteúdo não confiável que sequestra as instruções ou objetivos do agente.
+- **Injeção indireta de prompt:** injeção entregue através de dados que o agente recupera (documentos, páginas web, saídas de ferramentas).
+- **Isolamento de ferramentas (sandboxing):** isolar a execução de uma ferramenta para que não possa exceder sua autoridade prevista.
+- **Privilégio mínimo:** conceder a cada agente as permissões mínimas de que sua tarefa precisa.
+- **Identidade do agente:** um principal distinto e atribuível para cada agente, com âmbito limitado e revogável.
+- **Exfiltração de dados:** saída não autorizada de dados sensíveis através de saídas de ferramentas ou conteúdo renderizado.
+- **Trifeta letal:** a combinação perigosa de acesso a dados privados, exposição a conteúdo não confiável e capacidade de comunicar para o exterior.
+
+## Definição
+
+> A **segurança para sistemas agênticos** é a disciplina do harness que trata o modelo como um componente não confiável e manipulável, e constrói controles de identidade, permissões, isolamento e saída de dados para que o dano máximo que qualquer agente comprometido possa causar seja limitado, atribuível e auditado.
+
+## Explicação detalhada
+
+A ameaça fundacional é a **injeção de prompt**, e o erro fundacional é tentar resolvê-la dentro do modelo. Nenhum grau de endurecimento do prompt de sistema trava de forma confiável uma instrução suficientemente astuta embebida em conteúdo recuperado, porque o modelo não tem uma fronteira robusta e de princípio entre “dados” e “instrução”. A injeção indireta é a variante perigosa: um agente que resume uma página web ou lê um ticket pode ser tomado pelo texto que o atacante ali plantou. A resposta do harness é **arquitetônica, não de prompting**: assumir que a injeção terá sucesso por vezes e garantir que um agente sequestrado continua sem poder fazer nada que suas *permissões* proíbam. Os guarda-corpos de entrada (detecção de injeção e jailbreak) reduzem a *frequência* das injeções bem-sucedidas; os controles de permissões e de saída limitam a *consequência*. São precisos os dois; nenhum basta por si só.
+
+O **privilégio mínimo e a identidade do agente** são a espinha dorsal da segurança agêntica. Cada agente deveria rodar como um principal distinto e atribuível, com credenciais limitadas exatamente aos recursos de que sua tarefa precisa: tokens de vida curta, âmbitos OAuth estreitos, apenas leitura onde não for preciso escrever e isolamento de dados por inquilino aplicado *abaixo* do agente (na camada de dados), nunca pedindo educadamente ao modelo que não saia da sua faixa. Quando um agente age em nome de um usuário, deve levar a autorização desse usuário e não uma conta de serviço com poderes absolutos, para que o agente nunca possa exceder o que o usuário poderia fazer diretamente. As credenciais devem ser injetadas pelo harness no momento da chamada, jamais colocadas na janela de contexto, onde uma injeção as poderia ler e exfiltrar.
+
+O **isolamento de ferramentas** confina a execução. As ferramentas que executam código fazem-no em caixas de areia efêmeras, com rede restringida e recursos limitados. Os catálogos de ferramentas estão em **lista de permitidos** por agente, de modo que um agente sequestrado não pode alcançar uma ferramenta que nunca lhe foi concedida. As ferramentas de alta consequência ficam por trás de uma aprovação humana (PAT-007 / PAT-001), para que mesmo uma chamada autorizada mas manipulada exija que uma pessoa a confirme. O princípio é a *defesa em profundidade*: a autorização decide *se* a chamada é permitida, a caixa de areia limita *o que pode tocar* e a porta de aprovação acrescenta um ponto de controle humano para as ações irreversíveis.
+
+A **exfiltração de dados** é o risco agêntico mais subestimado. A “trifeta letal” — um agente com (1) acesso a dados privados, (2) exposição a conteúdo não confiável e (3) capacidade de comunicar para o exterior — é explorável: instruções injetadas dizem ao agente que embuta segredos num pedido de saída, no URL de uma imagem renderizada ou no argumento de uma ferramenta. O harness quebra a trifeta eliminando pelo menos uma das suas pernas nos contextos sensíveis: restringir os destinos de saída a uma lista de permitidos, executar verificações de prevenção de fuga de dados sobre cada carga de saída, remover ou fixar a renderização de conteúdo externo e proibir que o agente construa URL de saída arbitrários. Se um agente tiver de tocar dados privados, sua capacidade de comunicar para o exterior tem de estar fortemente restringida, e vice-versa.
+
+Tudo isto assenta na **observabilidade e na auditabilidade** (HRN-006): cada ação, a identidade que a realizou, a decisão de permissão e a verificação de saída têm de ficar registadas de forma imutável. Uma segurança que não se consegue demonstrar é uma segurança que não se tem. Estes controles implementam as obrigações definidas no quadro de governança (GOV-001) e encaixam na taxonomia geral do harness (HRN-003).
+
+## Evidência de produção
+
+> **Cenário ilustrativo e representativo.** Nível de evidência: teórico · Confiança: média · Fonte: observação de indústria, experiência pessoal. As descrições seguintes são padrões representativos de ataque e mitigação, não medições de uma implantação verificada concreta.
+
+- **Contexto:** um agente de suporte ao cliente com acesso a uma base de conhecimento e capacidade de enviar emails a clientes.
+- **Cenário:** um atacante planta texto de injeção num ticket de suporte tentando fazer com que o agente envie por email os dados da conta de outro cliente para um endereço externo.
+- **Tecnologia:** credenciais com âmbito por agente, lista de permitidos de saída, prevenção de fuga de dados sobre o email de saída, detecção de injeção no conteúdo recuperado, registro de auditoria.
+- **Carga:** alto volume de tickets, com uma fração pequena mas não nula carregando tentativas de injeção.
+- **Resultados (representativos):** em implantações desta forma, os controles arquitetônicos (lista de permitidos de saída + prevenção de fuga + privilégio mínimo) bloqueiam a *consequência* da injeção mesmo quando a detecção falha a *tentativa*, levando a exfiltração bem-sucedida para perto de zero, enquanto a detecção de injeção por si só deixa risco residual.
+
+### Lições aprendidas
+
+As estratégias baseadas apenas em detecção acabam por falhar; as defesas confiáveis são as arquitetônicas, as que limitam a consequência. Quebrar a trifeta letal — sobretudo restringindo a saída — faz mais pela segurança do que qualquer classificador isolado.
+
+## Modos de falha observados
+
+| Modo de falha | Gatilho | Mitigação |
+|---|---|---|
+| Injeção direta de prompt | Instrução maliciosa do usuário | Guarda-corpos de entrada + limitação de permissões |
+| Injeção indireta | Texto malicioso nos dados recuperados | Tratar todo o conteúdo recuperado como não confiável; controles de saída |
+| Exfiltração de dados | Trifeta letal explorada | Quebrar a trifeta: lista de permitidos de saída + prevenção de fuga |
+| Escalada de privilégios | Credenciais de serviço demasiado amplas | Credenciais com âmbito por agente e vida curta; autorização delegada pelo usuário |
+| Fuga de credenciais | Segredos na janela de contexto | Injetar as credenciais no momento da chamada, nunca no contexto |
+| Fuga da caixa de areia | Código ou rede sem restrições nas ferramentas | Caixas de areia efêmeras, isoladas da rede e com recursos limitados |
+| Delegado confuso | O agente é usado como proxy para ações proibidas | Transportar a identidade de quem chama; autorizar no efetor |
+
+## KPIs
+
+| Métrica | Objetivo | Notas |
+|---|---|---|
+| Taxa de exfiltração bem-sucedida | → 0 | A métrica que mais importa |
+| Abrangência da detecção de injeção | Alta | Reduz a frequência de tentativas, não é a única defesa |
+| Estreiteza do âmbito de permissões | Concessões mínimas | Auditar permissões não usadas ou demasiado amplas |
+| Cobertura da lista de permitidos de saída | 100 % | Sem destinos de saída arbitrários |
+| Tempo médio até à revogação | Baixo | Revogação da identidade de um agente comprometido |
+| Completude de auditoria | 100 % | Toda a ação atribuível |
+
+## Métricas de custo
+
+- **Custo de inferência dos guarda-corpos:** os classificadores de injeção e de fuga de dados acrescentam inferência auxiliar por pedido; tem de ser orçamentada dentro do custo por tarefa.
+- **Sobrecusto das caixas de areia:** o arranque de uma caixa efêmera acrescenta latência às ferramentas de código; amortiza-se com pools quentes.
+- **Custo de engenharia:** a identidade com âmbito e a lista de permitidos de saída são trabalho de IAM feito à partida que se rentabiliza em todos os agentes.
+
+## Características de escalabilidade
+
+Os controles de permissões e identidade escalam com a infraestrutura de IAM e de segredos, sem estado por chamada. Os classificadores de guarda-corpo escalam com a capacidade de inferência e são o custo de débito; faça curto-circuito antes com verificações deterministas baratas (listas de permitidos, expressões regulares, esquema). As caixas de areia escalam com um pool gerido; os pools quentes trocam custo ocioso por latência. Os controles de saída escalam trivialmente e nunca deveriam ser o gargalo: são o controle com maior valor por custo de toda a pilha.
+
+## Conteúdo relacionado
+
+- HRN-003 — O lugar da segurança na taxonomia do harness.
+- GOV-001 — Obrigações de governança que estes controles de segurança implementam.
+- PAT-007 — Padrão de controle de ferramentas e permissões (isolamento e uso de ferramentas com porta).
+
+## Referências
+
+- OWASP Top 10 para aplicações LLM (LLM01 injeção de prompt, LLM06 divulgação de informação sensível).
+- Simon Willison, “The lethal trifecta for AI agents”.
+- NIST AI RMF e NIST SP 800-53 (privilégio mínimo, identidade).
+- MITRE ATLAS — panorama de ameaças adversárias para sistemas de IA.
+
+## Perguntas frequentes
+
+**P: A injeção de prompt pode ser totalmente prevenida?**
+R: Não. Desenhe contando com ela: assuma que por vezes terá sucesso e limite a consequência com privilégio mínimo, controle de saída e isolamento.
+
+**P: Qual é o controle de maior valor?**
+R: Quebrar a trifeta letal; da forma mais barata, restringindo a saída a uma lista de permitidos com prevenção de fuga de dados, para que um agente sequestrado não possa exfiltrar nada.
+
+**P: Os agentes devem compartilhar uma conta de serviço?**
+R: Não. Dê a cada agente uma identidade distinta, com âmbito limitado e vida curta, e faça-a transportar a autorização do usuário que chama para que nunca possa exceder os direitos desse usuário.

package/content/harness/HRN-012-case-studies-in-harness-engineering.es.md

@@ -0,0 +1,120 @@
+---
+title: "Casos de estudio en Ingeniería de Harness"
+summary: "Tres casos compuestos y anonimizados analizados por su harness: qué falló, qué control lo habría evitado y qué se aprendió al llevarlos a producción."
+---
+
+# Casos de estudio en Ingeniería de Harness
+
+## Resumen ejecutivo
+
+Este capítulo aterriza las capas abstractas del harness en tres historias de extremo a extremo. Cada una es un **caso compuesto, representativo y anonimizado**, sintetizado a partir de patrones habituales en la industria: no es el relato de un despliegue concreto con nombre y apellidos ni una fuente de métricas verificadas. Lo que interesa es mostrar cómo interactúan las capas bajo carga, cómo la memoria, la planificación, la orquestación, la gobernanza, la seguridad y la observabilidad dejan de ser capítulos separados y se convierten en un solo sistema. Leídos en conjunto, los casos refuerzan la tesis de que la fiabilidad en los agentes empresariales es una propiedad de ingeniería del harness, no una propiedad emergente del modelo.
+
+## Conceptos clave
+
+- **Caso de estudio compuesto:** un escenario ilustrativo ensamblado a partir de patrones recurrentes del mundo real, explícitamente no un despliegue verificado concreto.
+- **De extremo a extremo:** desde la ingesta de la intención hasta la acción verificada, gobernada y observada.
+- **Interacción de capas del harness:** cómo se componen memoria, planificación, orquestación, gobernanza, seguridad y observabilidad.
+
+## Definición
+
+> Un **caso de estudio de Ingeniería de Harness** es una narrativa estructurada que sigue un objetivo a través de todas las capas de un sistema agéntico para dejar a la vista las decisiones de diseño, los modos de fallo y las concesiones que determinan la fiabilidad.
+
+## Explicación detallada
+
+### Caso 1 — Operaciones financieras: el agente de conciliación
+
+> Caso compuesto representativo. Sin métricas verificadas; los rangos son ilustrativos.
+
+**Objetivo.** Conciliar de forma autónoma las transacciones diarias entre dos libros contables y remediar las discrepancias bajo una autoridad de gasto estricta.
+
+**Diseño del harness.** La planificación (HRN-009) descompone el objetivo en un DAG: extraer, casar, clasificar discrepancias, remediar, informar. La orquestación (HRN-010) lo ejecuta sobre un **motor de flujo duradero**, de modo que una caída nocturna se reanuda desde el último punto de control en lugar de reiniciarse, algo crítico porque algunos pasos de remediación mueven dinero y no deben ejecutarse dos veces jamás (claves de idempotencia y compensación saga). La gobernanza (HRN-008) coloca una **puerta de aprobación** en cualquier remediación por encima de un umbral; por debajo, el agente actúa de forma autónoma con registro de auditoría completo. La memoria (HRN-005) guarda las reglas de conciliación y los precedentes de resolución. La observabilidad (HRN-006) traza cada decisión de emparejamiento.
+
+**Resultado (ilustrativo).** El agente liquida de forma autónoma la cola larga de discrepancias triviales y escala las de consecuencia, desplazando el esfuerzo humano de *hacer* la conciliación a *aprobar* excepciones. **Lección:** la durabilidad y la idempotencia fueron las decisiones portantes; la «inteligencia» fue la parte fácil.
+
+### Caso 2 — Atención al cliente: el agente de resolución
+
+> Caso compuesto representativo. Sin métricas verificadas; los rangos son ilustrativos.
+
+**Objetivo.** Resolver tickets de soporte de extremo a extremo —responder preguntas, actualizar cuentas, emitir créditos pequeños— sin filtrar nunca los datos de un cliente a otro y sin ser secuestrado por el contenido del ticket.
+
+**Diseño del harness.** Este es un harness **con la seguridad primero** (HRN-011). Cada instancia de agente porta la autorización *del cliente solicitante*, de modo que el aislamiento de datos se aplica por debajo del modelo y no mediante prompting. El contenido recuperado de la base de conocimiento y del ticket se trata como no confiable; la **salida está en lista de permitidos** y los mensajes salientes pasan por prevención de fuga de datos, rompiendo la trifecta letal incluso cuando la detección de inyección se pierde un intento. Una topología de agente único (HRN-010) lo mantiene simple; un paso de reflexión (autocomprobación al estilo PAT-003) revisa la respuesta redactada antes de enviarla. La gobernanza envía a un humano los créditos por encima de un umbral pequeño.
+
+**Resultado (ilustrativo).** La mayoría de los tickets se resuelve sin intervención humana; los intentos de inyección en los tickets no llegan a causar daño porque la *consecuencia* está acotada por los permisos y el control de salida, no solo por la detección. **Lección:** la seguridad arquitectónica ganó a la seguridad por clasificador; la victoria vino de restringir lo que un agente secuestrado *podía* hacer.
+
+### Caso 3 — Trabajo del conocimiento: el agente de investigación y síntesis
+
+> Caso compuesto representativo. Sin métricas verificadas; los rangos son ilustrativos.
+
+**Objetivo.** Responder preguntas internas complejas con una síntesis citada y de fiar sobre un corpus grande.
+
+**Diseño del harness.** Una topología **supervisor/trabajador** (HRN-010, PAT-002 + PAT-005): el supervisor descompone la pregunta y despacha en paralelo trabajadores de recuperación y análisis, y después un agregador reconcilia sus hallazgos en una respuesta con citas. La memoria (HRN-005) aporta el contexto de recuperación; la planificación (HRN-009) es entrelazada, porque el camino depende de lo que aflore la recuperación temprana. La evaluación (HRN-007) ejecuta una comprobación de anclaje con LLM como juez que *rechaza la respuesta si las afirmaciones no están citadas*, realimentando una replanificación. La observabilidad traza el abanico para que el coste y la latencia por trabajador sean visibles.
+
+**Resultado (ilustrativo).** El abanico paralelo mejora la latencia frente a la investigación secuencial a cambio de un mayor gasto en tokens; la puerta de anclaje es lo que hace la salida suficientemente fiable como para publicarla. **Lección:** aquí el multiagente se ganó su complejidad precisamente por el *paralelismo* y por la necesidad de verificar antes de responder, no porque el multiagente sea inherentemente mejor.
+
+### Observaciones transversales
+
+En los tres se repiten las mismas verdades: (1) gana la topología más simple que cumple el requisito; (2) la durabilidad y la idempotencia, no la astucia, deciden si un agente de larga duración es apto para producción; (3) la gobernanza y la seguridad son capas *de ejecución*, no documentos; (4) la verificación (evaluación) antes de actuar es lo que convierte una salida plausible en una salida de fiar. Todo ello enlaza con las arquitecturas de referencia (ARCH-001, ARCH-002) y reformula la tesis central de HRN-001: la fiabilidad se construye dentro del harness.
+
+## Evidencia de producción
+
+> **Escenarios ilustrativos y representativos.** Nivel de evidencia: teórico · Confianza: media · Fuente: observación de industria, experiencia personal. Los tres casos son compuestos anonimizados ensamblados a partir de patrones recurrentes. No contienen mediciones de ningún despliegue de producción verificado, y toda cantidad es un rango ilustrativo.
+
+- **Contexto:** operaciones financieras, atención al cliente y trabajo del conocimiento empresarial.
+- **Escenario:** automatización agéntica de extremo a extremo bajo restricciones empresariales reales (autoridad de gasto, aislamiento de datos, confianza en las citas).
+- **Tecnología:** motores de flujo duradero, identidad de agente con alcance, listas de permitidos de salida, orquestación supervisor/trabajador, evaluación con LLM como juez.
+- **Resultados:** direccionales y cualitativos; se presentan para ilustrar concesiones de diseño, no para afirmar resultados medidos.
+
+### Lecciones aprendidas
+
+La lección recurrente es la contención: los equipos que tuvieron éxito añadieron complejidad (multiagente, autonomía) *solo* allí donde un requisito concreto lo justificaba, e invirtieron pronto en las capas poco vistosas —durabilidad, identidad, auditoría— que deciden si algo funciona en producción.
+
+## Modos de fallo observados
+
+| Caso | Modo de fallo dominante | Mitigación decisiva |
+|---|---|---|
+| Conciliación | Ejecutar dos veces un paso que mueve dinero al reanudar | Claves de idempotencia + compensación saga |
+| Soporte | Exfiltración de datos vía contenido inyectado en el ticket | Autorización delegada por el usuario + lista de permitidos de salida + prevención de fuga |
+| Investigación | Afirmaciones sin respaldo presentadas como hechos | Puerta de evaluación de anclaje antes de responder |
+
+## KPIs
+
+| Métrica | Conciliación | Soporte | Investigación |
+|---|---|---|---|
+| Tasa de finalización de tarea | Alta (con escalado) | Alta | Alta |
+| Tasa de intervención humana | Baja (solo excepciones) | Baja | Moderada (revisión) |
+| Tasa de incidentes de seguridad | → 0 (gasto con puerta) | → 0 (radio de impacto acotado) | → 0 (solo con citas) |
+| Latencia | Tolerante a lotes | Interactiva | Mejorada por el abanico |
+| Coste por tarea | Bajo | Bajo | Mayor (multiagente) |
+
+## Métricas de coste
+
+- **Conciliación:** barata por tarea (agente único, determinista); el coste dominante es la aprobación humana de excepciones.
+- **Soporte:** barata por tarea; la inferencia de guardarraíles y prevención de fuga es el añadido marginal.
+- **Investigación:** la más cara por tarea, por el gasto en tokens del multiagente; se justifica por la latencia en paralelo y la calidad verificada.
+
+## Características de escalado
+
+Los casos de agente único (conciliación, soporte) escalan horizontalmente y barato, acotados por los límites de tasa de las herramientas externas y por la capacidad de aprobación humana. El caso multiagente de investigación escala las subtareas en paralelo hasta los límites de tasa de la recuperación compartida, con el coste en tokens creciendo por cada trabajador añadido: el clásico intercambio latencia-coste que define cuándo merece la pena el multiagente.
+
+## Contenido relacionado
+
+- ARCH-001 — Arquitectura de referencia que ejemplifica flujos duraderos de agente único.
+- ARCH-002 — Arquitectura de referencia que ejemplifica la orquestación supervisor/trabajador.
+- HRN-001 — Definición y panorama (la tesis que estos casos refuerzan).
+
+## Referencias
+
+- Anthropic, «Building Effective Agents» y publicaciones sobre sistemas de investigación multiagente.
+- Post-mortems y escritos de arquitectura del sector sobre flujos agénticos duraderos.
+- Los capítulos HRN-005 a HRN-011, que estos casos componen.
+
+## Preguntas frecuentes
+
+**P: ¿Son despliegues reales?**
+R: No. Son compuestos anonimizados ensamblados a partir de patrones recurrentes de la industria, presentados para ilustrar concesiones de diseño. No contienen métricas de producción verificadas.
+
+**P: ¿Cuál es la lección más transferible?**
+R: Añade complejidad solo donde un requisito la exija, e invierte primero en durabilidad, identidad y auditoría: las capas que deciden si un agente sobrevive a producción.
+
+**P: ¿Por qué el multiagente aparece solo en el caso 3?**
+R: Porque es el único caso donde el paralelismo y la verificación justificaban el coste de coordinación. Los otros son deliberadamente de agente único.

package/content/harness/HRN-012-case-studies-in-harness-engineering.md

@@ -0,0 +1,157 @@
+---
+id: HRN-012
+title: Case Studies in Harness Engineering
+domain: Harness
+category: Case Studies
+status: Draft
+author: Santiago Santa María
+created: 2026-06-21
+updated: 2026-06-21
+summary: Three representative, anonymized composite case studies showing how harness layers—memory, planning, orchestration, governance, security, observability—combine end-to-end to make enterprise agents reliable.
+evidence_level: theoretical
+confidence_level: medium
+source_type:
+  - industry_observation
+  - personal_experience
+related:
+  - ARCH-001
+  - ARCH-002
+  - HRN-001
+tags:
+  - case-studies
+  - end-to-end
+  - reliability
+  - enterprise-agents
+---
+
+# Case Studies in Harness Engineering
+
+## Executive Summary
+
+This chapter grounds the abstract harness layers in three end-to-end stories. Each is a **representative, anonymized composite** — synthesized from common patterns across the industry, not an account of a single named deployment, and not a source of verified metrics. The point is to show how the layers interact under load: how memory, planning, orchestration, governance, security, and observability stop being separate chapters and become one system. Read together, the cases reinforce the thesis that reliability in enterprise agents is an engineering property of the harness, not an emergent property of the model.
+
+## Key Concepts
+
+- **Composite case study:** an illustrative scenario assembled from recurring real-world patterns, explicitly not a verified single deployment.
+- **End-to-end:** spanning ingestion of intent through verified, governed action and observation.
+- **Harness layer interaction:** how memory, planning, orchestration, governance, security, and observability compose.
+
+## Definition
+
+> A **harness engineering case study** is a structured narrative that traces a goal through every layer of an agentic system to expose the design decisions, failure modes, and trade-offs that determine reliability.
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    INTENT[User Intent] --> PLAN[Planning HRN-009]
+    PLAN --> ORC[Orchestration HRN-010]
+    ORC --> MEM[(Memory HRN-005)]
+    ORC --> GOV[Governance HRN-008]
+    GOV --> SEC[Security HRN-011]
+    SEC --> TOOLS[Tools / Effectors]
+    TOOLS --> OBS[Observability HRN-006]
+    OBS --> EVAL[Evaluation HRN-007]
+    EVAL -.feedback.-> PLAN
+    MEM -.context.-> PLAN
+```
+
+## Detailed Explanation
+
+### Case Study 1 — Financial Operations: the Reconciliation Agent
+
+> Representative composite. No verified metrics; ranges are illustrative.
+
+**Goal.** Autonomously reconcile daily transactions across two ledgers and remediate discrepancies under a strict spend authority.
+
+**Harness design.** Planning (HRN-009) decomposes the goal into a DAG: extract, match, classify discrepancies, remediate, report. Orchestration (HRN-010) runs it on a **durable workflow engine** so an overnight crash resumes from the last checkpoint rather than restarting — critical because some remediation steps move money and must never double-execute (idempotency keys + saga compensation). Governance (HRN-008) places an **approval gate** on any remediation above a threshold; below it, the agent acts autonomously with full audit logging. Memory (HRN-005) holds reconciliation rules and prior-resolution precedents. Observability (HRN-006) traces every match decision.
+
+**Outcome (illustrative).** The agent clears the long tail of trivial discrepancies autonomously and escalates the consequential ones, shifting human effort from *doing* reconciliation to *approving* exceptions. **Lesson:** durability + idempotency were the load-bearing decisions; the "intelligence" was the easy part.
+
+### Case Study 2 — Customer Support: the Resolution Agent
+
+> Representative composite. No verified metrics; ranges are illustrative.
+
+**Goal.** Resolve inbound support tickets end-to-end — answer questions, update accounts, issue small credits — while never leaking one customer's data to another and never being hijacked by ticket content.
+
+**Harness design.** This is a **security-first** harness (HRN-011). Each agent instance carries the *requesting customer's* authorization, so data isolation is enforced below the model, not by prompting. Retrieved knowledge-base and ticket content is treated as untrusted; **egress is allowlisted** and outbound messages pass DLP — breaking the lethal trifecta even when injection detection misses an attempt. A single-agent topology (HRN-010) keeps it simple; a reflection step (PAT-003-style self-check) reviews the drafted reply before send. Governance gates credits above a small threshold to a human.
+
+**Outcome (illustrative).** Most tickets resolve without human touch; injection attempts in tickets fail to cause harm because the *consequence* is bounded by permissions and egress control, not merely by detection. **Lesson:** architectural security beat classifier security; the win came from constraining what a hijacked agent *could* do.
+
+### Case Study 3 — Knowledge Work: the Research-and-Synthesis Agent
+
+> Representative composite. No verified metrics; ranges are illustrative.
+
+**Goal.** Answer complex internal questions with cited, trustworthy synthesis over a large corpus.
+
+**Harness design.** A **supervisor/worker** topology (HRN-010, PAT-002 + PAT-005): the supervisor decomposes the question and dispatches parallel retrieval and analysis workers, then an aggregator reconciles their findings into a cited answer. Memory (HRN-005) supplies retrieval context; planning (HRN-009) is interleaved because the path depends on what early retrieval surfaces. Evaluation (HRN-007) runs an LLM-as-judge groundedness check that *fails the answer if claims aren't cited*, feeding back into a replan. Observability traces the fan-out so cost and latency per worker are visible.
+
+**Outcome (illustrative).** Parallel fan-out improves latency over sequential research at the cost of higher token spend; the groundedness gate is what makes the output trustworthy enough to ship. **Lesson:** multi-agent earned its complexity here specifically because of *parallelism* and the need to verify before answering — not because multi-agent is inherently better.
+
+### Cross-cutting observations
+
+Across all three, the same truths recur: (1) the simplest topology that meets the requirement wins; (2) durability and idempotency, not cleverness, decide whether a long-running agent is production-grade; (3) governance and security are *runtime* layers, not documents; (4) verification (evaluation) before action is what converts plausible output into trustworthy output. These connect to the reference architectures (ARCH-001, ARCH-002) and restate the core thesis of HRN-001: reliability is engineered into the harness.
+
+## Production Evidence
+
+> **Illustrative / representative scenarios.** Evidence level: theoretical · Confidence: medium · Source: industry_observation, personal_experience. All three case studies are anonymized composites assembled from recurring patterns. They contain no measurements from any single verified production deployment, and any quantities are illustrative ranges.
+
+- **Context:** Financial operations, customer support, and enterprise knowledge work.
+- **Scenario:** End-to-end agentic automation under real enterprise constraints (spend authority, data isolation, citation trust).
+- **Technology:** Durable workflow engines, scoped agent identity, egress allowlists, supervisor/worker orchestration, LLM-as-judge evaluation.
+- **Results:** Directional and qualitative; presented to illustrate design trade-offs, not to assert benchmarked outcomes.
+
+### Lessons Learned
+
+The recurring lesson is restraint: teams that succeeded added complexity (multi-agent, autonomy) *only* where a specific requirement justified it, and invested early in the unglamorous layers — durability, identity, audit — that determine whether anything works in production.
+
+## Observed Failure Modes
+
+| Case | Dominant Failure Mode | Decisive Mitigation |
+|---|---|---|
+| Reconciliation | Double-executing a money-moving step on resume | Idempotency keys + saga compensation |
+| Support | Data exfiltration via injected ticket content | User-delegated authZ + egress allowlist + DLP |
+| Research | Unsupported claims presented as fact | Groundedness eval gate before answer |
+
+## KPIs
+
+| Metric | Reconciliation | Support | Research |
+|---|---|---|---|
+| Task completion rate | High (with escalation) | High | High |
+| Human-touch rate | Low (exceptions only) | Low | Moderate (review) |
+| Safety incident rate | → 0 (gated spend) | → 0 (bounded blast radius) | → 0 (cited only) |
+| Latency | Batch-tolerant | Interactive | Improved by fan-out |
+| Cost per task | Low | Low | Higher (multi-agent) |
+
+## Cost Metrics
+
+- **Reconciliation:** cheap per task (single agent, deterministic); dominant cost is human approval of exceptions.
+- **Support:** cheap per task; guardrail/DLP inference is the marginal add.
+- **Research:** highest per task due to multi-agent token spend; justified by parallel latency and verified quality.
+
+## Scaling Characteristics
+
+The single-agent cases (reconciliation, support) scale horizontally and cheaply, bounded by external-tool rate limits and human approval capacity. The multi-agent research case scales sub-tasks in parallel up to shared-retrieval rate limits, with token cost growing per added worker — the classic latency-vs-cost trade that defines when multi-agent is worth it.
+
+## Related Content
+
+- ARCH-001 — Reference architecture exemplifying single-agent durable workflows.
+- ARCH-002 — Reference architecture exemplifying supervisor/worker orchestration.
+- HRN-001 — Definition and Overview (the thesis these cases reinforce).
+
+## References
+
+- Anthropic, "Building Effective Agents" and multi-agent research-system writeups.
+- Industry post-mortems and architecture writeups on durable agentic workflows.
+- The harness chapters HRN-005 through HRN-011, which these cases compose.
+
+## FAQs
+
+**Q: Are these real deployments?**
+A: No. They are anonymized composites assembled from recurring industry patterns, presented to illustrate design trade-offs. They contain no verified production metrics.
+
+**Q: What is the single most transferable lesson?**
+A: Add complexity only where a requirement demands it, and invest first in durability, identity, and audit — the layers that decide whether an agent survives production.
+
+**Q: Why include multi-agent only in case 3?**
+A: Because that is the only case where parallelism and verification justified the coordination cost. The others are deliberately single-agent.

package/content/harness/HRN-012-case-studies-in-harness-engineering.pt.md

@@ -0,0 +1,120 @@
+---
+title: "Estudos de caso em Engenharia de Harness"
+summary: "Três casos compostos e anonimizados analisados pelo seu harness: o que falhou, que controle o teria evitado e o que se aprendeu ao levá-los para produção."
+---
+
+# Estudos de caso em Engenharia de Harness
+
+## Resumo executivo
+
+Este capítulo assenta as camadas abstratas do harness em três histórias de ponta a ponta. Cada uma é um **caso composto, representativo e anonimizado**, sintetizado a partir de padrões comuns na indústria: não é o relato de uma implantação concreta com nome próprio nem uma fonte de métricas verificadas. O que interessa é mostrar como as camadas interagem sob carga, como a memória, o planejamento, a orquestração, a governança, a segurança e a observabilidade deixam de ser capítulos separados e se tornam um só sistema. Lidos em conjunto, os casos reforçam a tese de que a confiabilidade nos agentes empresariais é uma propriedade de engenharia do harness, não uma propriedade emergente do modelo.
+
+## Conceitos-chave
+
+- **Estudo de caso composto:** um cenário ilustrativo montado a partir de padrões recorrentes do mundo real, explicitamente não uma implantação verificada concreta.
+- **De ponta a ponta:** desde a recepção da intenção até à ação verificada, governada e observada.
+- **Interação de camadas do harness:** como se compõem memória, planejamento, orquestração, governança, segurança e observabilidade.
+
+## Definição
+
+> Um **estudo de caso de Engenharia de Harness** é uma narrativa estruturada que segue um objetivo através de todas as camadas de um sistema agêntico para expor as decisões de desenho, os modos de falha e as compensações que determinam a confiabilidade.
+
+## Explicação detalhada
+
+### Caso 1 — Operações financeiras: o agente de reconciliação
+
+> Caso composto representativo. Sem métricas verificadas; os intervalos são ilustrativos.
+
+**Objetivo.** Reconciliar autonomamente as transações diárias entre dois livros contabilísticos e remediar as discrepâncias sob uma autoridade de despesa estrita.
+
+**Desenho do harness.** O planejamento (HRN-009) decompõe o objetivo num DAG: extrair, casar, classificar discrepâncias, remediar, reportar. A orquestração (HRN-010) executa-o sobre um **motor de fluxo duradouro**, de modo que uma queda noturna retoma a partir do último ponto de controle em vez de reiniciar — crítico porque alguns passos de remediação movem dinheiro e nunca podem ser executados duas vezes (chaves de idempotência e compensação saga). A governança (HRN-008) coloca uma **porta de aprovação** em qualquer remediação acima de um limiar; abaixo dele, o agente age autonomamente com registro de auditoria completo. A memória (HRN-005) guarda as regras de reconciliação e os precedentes de resolução. A observabilidade (HRN-006) traça cada decisão de correspondência.
+
+**Resultado (ilustrativo).** O agente liquida autonomamente a cauda longa de discrepâncias triviais e escala as de consequência, deslocando o esforço humano de *fazer* a reconciliação para *aprovar* exceções. **Lição:** a durabilidade e a idempotência foram as decisões portantes; a “inteligência” foi a parte fácil.
+
+### Caso 2 — Apoio ao cliente: o agente de resolução
+
+> Caso composto representativo. Sem métricas verificadas; os intervalos são ilustrativos.
+
+**Objetivo.** Resolver tickets de apoio de ponta a ponta — responder a perguntas, atualizar contas, emitir pequenos créditos — sem nunca deixar escapar os dados de um cliente para outro e sem ser sequestrado pelo conteúdo do ticket.
+
+**Desenho do harness.** Este é um harness **com a segurança primeiro** (HRN-011). Cada instância de agente transporta a autorização *do cliente que pede*, de modo que o isolamento de dados é aplicado abaixo do modelo e não por prompting. O conteúdo recuperado da base de conhecimento e do ticket é tratado como não confiável; a **saída está em lista de permitidos** e as mensagens de saída passam por prevenção de fuga de dados, quebrando a trifeta letal mesmo quando a detecção de injeção falha uma tentativa. Uma topologia de agente único (HRN-010) mantém-no simples; um passo de reflexão (autoverificação ao estilo PAT-003) revê a resposta redigida antes do envio. A governança encaminha para um humano os créditos acima de um limiar pequeno.
+
+**Resultado (ilustrativo).** A maioria dos tickets se resolve sem intervenção humana; as tentativas de injeção nos tickets não chegam a causar dano porque a *consequência* está limitada pelas permissões e pelo controle de saída, não apenas pela detecção. **Lição:** a segurança arquitetônica ganhou à segurança por classificador; a vitória veio de restringir o que um agente sequestrado *podia* fazer.
+
+### Caso 3 — Trabalho do conhecimento: o agente de investigação e síntese
+
+> Caso composto representativo. Sem métricas verificadas; os intervalos são ilustrativos.
+
+**Objetivo.** Responder a perguntas internas complexas com uma síntese citada e de confiança sobre um corpus grande.
+
+**Desenho do harness.** Uma topologia **supervisor/trabalhador** (HRN-010, PAT-002 + PAT-005): o supervisor decompõe a pergunta e despacha em paralelo trabalhadores de recuperação e análise, e depois um agregador reconcilia seus achados numa resposta com citações. A memória (HRN-005) fornece o contexto de recuperação; o planejamento (HRN-009) é entrelaçado, porque o caminho depende do que a recuperação inicial trouxer à superfície. A avaliação (HRN-007) executa uma verificação de ancoragem com LLM como juiz que *rejeita a resposta se as afirmações não estiverem citadas*, realimentando um replanejamento. A observabilidade traça o leque para que o custo e a latência por trabalhador sejam visíveis.
+
+**Resultado (ilustrativo).** O leque paralelo melhora a latência diante da investigação sequencial à custa de uma maior despesa em tokens; a porta de ancoragem é o que torna a saída suficientemente confiável para ser publicada. **Lição:** aqui o multiagente ganhou sua complexidade precisamente pelo *paralelismo* e pela necessidade de verificar antes de responder, não porque o multiagente seja inerentemente melhor.
+
+### Observações transversais
+
+Nos três se repetem as mesmas verdades: (1) ganha a topologia mais simples que cumpre o requisito; (2) a durabilidade e a idempotência, não a esperteza, decidem se um agente de longa duração é apto para produção; (3) a governança e a segurança são camadas *de execução*, não documentos; (4) a verificação (avaliação) antes de agir é o que converte uma saída plausível numa saída de confiança. Tudo isto se liga às arquiteturas de referência (ARCH-001, ARCH-002) e reformula a tese central de HRN-001: a confiabilidade é construída dentro do harness.
+
+## Evidência de produção
+
+> **Cenários ilustrativos e representativos.** Nível de evidência: teórico · Confiança: média · Fonte: observação de indústria, experiência pessoal. Os três casos são compostos anonimizados montados a partir de padrões recorrentes. Não contêm medições de nenhuma implantação de produção verificada, e qualquer quantidade é um intervalo ilustrativo.
+
+- **Contexto:** operações financeiras, suporte ao cliente e trabalho do conhecimento empresarial.
+- **Cenário:** automação agêntica de ponta a ponta sob restrições empresariais reais (autoridade de despesa, isolamento de dados, confiança nas citações).
+- **Tecnologia:** motores de fluxo duradouro, identidade de agente com âmbito, listas de permitidos de saída, orquestração supervisor/trabalhador, avaliação com LLM como juiz.
+- **Resultados:** direcionais e qualitativos; apresentados para ilustrar compensações de desenho, não para afirmar resultados medidos.
+
+### Lições aprendidas
+
+A lição recorrente é a contenção: as equipes que tiveram sucesso acrescentaram complexidade (multiagente, autonomia) *apenas* onde um requisito concreto o justificava, e investiram cedo nas camadas pouco vistosas — durabilidade, identidade, auditoria — que decidem se alguma coisa funciona em produção.
+
+## Modos de falha observados
+
+| Caso | Modo de falha dominante | Mitigação decisiva |
+|---|---|---|
+| Reconciliação | Executar duas vezes um passo que move dinheiro ao retomar | Chaves de idempotência + compensação saga |
+| Apoio ao cliente | Exfiltração de dados via conteúdo injetado no ticket | Autorização delegada pelo usuário + lista de permitidos de saída + prevenção de fuga |
+| Investigação | Afirmações sem suporte apresentadas como fatos | Porta de avaliação de ancoragem antes de responder |
+
+## KPIs
+
+| Métrica | Reconciliação | Apoio ao cliente | Investigação |
+|---|---|---|---|
+| Taxa de conclusão de tarefa | Alta (com escalonamento) | Alta | Alta |
+| Taxa de intervenção humana | Baixa (só exceções) | Baixa | Moderada (revisão) |
+| Taxa de incidentes de segurança | → 0 (despesa com porta) | → 0 (raio de impacto limitado) | → 0 (só com citações) |
+| Latência | Tolerante a lotes | Interativa | Melhorada pelo leque |
+| Custo por tarefa | Baixo | Baixo | Maior (multiagente) |
+
+## Métricas de custo
+
+- **Reconciliação:** barata por tarefa (agente único, determinista); o custo dominante é a aprovação humana de exceções.
+- **Apoio ao cliente:** barata por tarefa; a inferência de guarda-corpos e prevenção de fuga é o acréscimo marginal.
+- **Investigação:** a mais cara por tarefa, pela despesa em tokens do multiagente; justifica-se pela latência em paralelo e pela qualidade verificada.
+
+## Características de escalabilidade
+
+Os casos de agente único (reconciliação, suporte ao cliente) escalam horizontalmente e de forma barata, limitados pelos limites de taxa das ferramentas externas e pela capacidade de aprovação humana. O caso multiagente de investigação escala as subtarefas em paralelo até aos limites de taxa da recuperação compartilhada, com o custo em tokens crescendo a cada trabalhador acrescentado: a clássica troca latência-custo que define quando vale a pena o multiagente.
+
+## Conteúdo relacionado
+
+- ARCH-001 — Arquitetura de referência que exemplifica fluxos duradouros de agente único.
+- ARCH-002 — Arquitetura de referência que exemplifica a orquestração supervisor/trabalhador.
+- HRN-001 — Definição e panorama (a tese que estes casos reforçam).
+
+## Referências
+
+- Anthropic, “Building Effective Agents” e publicações sobre sistemas de investigação multiagente.
+- Post-mortems e escritos de arquitetura do setor sobre fluxos agênticos duradouros.
+- Os capítulos HRN-005 a HRN-011, que estes casos compõem.
+
+## Perguntas frequentes
+
+**P: São implantações reais?**
+R: Não. São compostos anonimizados montados a partir de padrões recorrentes da indústria, apresentados para ilustrar compensações de desenho. Não contêm métricas de produção verificadas.
+
+**P: Qual é a lição mais transferível?**
+R: Acrescente complexidade apenas onde um requisito a exija, e invista primeiro em durabilidade, identidade e auditoria: as camadas que decidem se um agente sobrevive à produção.
+
+**P: Porque é que o multiagente aparece apenas no caso 3?**
+R: Porque é o único caso em que o paralelismo e a verificação justificavam o custo de coordenação. Os outros são deliberadamente de agente único.