santismm-knowledge-mcp 0.2.1

package/content/harness/HRN-003-the-harness-taxonomy.pt.md

@@ -0,0 +1,105 @@
+---
+title: "A taxonomia do harness"
+summary: "Decomposição precisa dos componentes do harness — memória, ferramentas, planejamento, orquestração, observabilidade, avaliação, governança e segurança — e de como encaixam entre si."
+---
+
+# A taxonomia do harness
+
+## Resumo executivo
+O harness não é um monólito: é um conjunto de componentes distintos, cada um com uma responsabilidade clara e interfaces claras com os restantes. Este capítulo apresenta a taxonomia canônica: oito componentes — memória, ferramentas, planejamento, orquestração, observabilidade, avaliação, governança e segurança — organizados em três camadas (o ciclo de execução, as preocupações transversais e os controles). A taxonomia é o mapa que o resto do manual preenche.
+
+## Conceitos-chave
+- **Componente:** uma parte delimitada do harness com uma única responsabilidade principal.
+- **Camada de execução:** os componentes que movem o ciclo percecionar–raciocinar–agir (planejamento, orquestração, memória, ferramentas).
+- **Camada transversal:** preocupações que instrumentam ou medem o ciclo sem estarem dentro dele (observabilidade, avaliação).
+- **Camada de controle:** preocupações que limitam o que o ciclo pode fazer (governança, segurança).
+- **Interface:** o contrato pelo qual dois componentes trocam informação ou autoridade.
+
+## Definição
+A **taxonomia do harness** é a decomposição canônica do andaime de engenharia de um sistema agêntico em componentes e camadas com nome, definindo a responsabilidade de cada componente e suas relações com os restantes. Serve como vocabulário compartilhado e como lista de verificação: um harness de qualidade produtiva tem de abordar conscientemente cada componente, mesmo que escolha uma implementação mínima.
+
+## Explicação detalhada
+
+A taxonomia organiza oito componentes em três camadas. A estratificação importa: diz quais componentes *fazem o trabalho*, quais *observam o trabalho* e quais *delimitam o trabalho*.
+
+### Camada de execução — move o ciclo
+Os componentes que produzem efetivamente o comportamento do agente.
+
+- **Planejamento e gestão de objetivos (HRN-009):** decompõe um objetivo em subobjetivos, decide a ação seguinte, gerencia o replanejamento quando um passo falha e detecta a conclusão ou o impasse. Responde a “o que deve acontecer a seguir?”.
+- **Orquestração (HRN-010):** o runtime que executa o ciclo: monta o contexto, chama o modelo, despacha chamadas a ferramentas, gerencia retentativas e tempos-limite, encaminha entre modelos ou subagentes e aplica orçamentos. Responde a “quem executa, com quê, e o que acontece à saída”.
+- **Memória (HRN-005):** governa o que entra no contexto do modelo: memória de trabalho de curto prazo, armazenamentos de longo prazo, recuperação, compressão e esquecimento. Responde a “o que o modelo vê e recorda”.
+- **Ferramentas / atuação:** os contratos tipados através dos quais o agente lê e escreve nos sistemas da empresa, com validação explícita de entradas, esquemas de saída, idempotência e semântica de falha. Responde a “como o agente afeta o mundo”.
+
+O modelo se situa *dentro* desta camada como componente invocado, não como o sistema. É o reenquadramento central de HRN-001.
+
+### Camada transversal — mede o ciclo
+Não produzem comportamento; tornam o comportamento visível e quantificável.
+
+- **Observabilidade (HRN-006):** rastreio, spans, registro estruturado, contabilização de tokens e custo, e reprodução. Transforma uma execução opaca e não determinística num artefacto inspecionável. Responde a “o que aconteceu, exatamente”.
+- **Avaliação (HRN-007):** medição offline e online da qualidade: conjuntos dourados, LLM como juiz, suites de regressão, métricas de conclusão de tarefa. Responde a “isto é realmente bom, e está melhorando ou piorando?”.
+
+Observabilidade e avaliação são codependentes: a avaliação precisa dos traços que a observabilidade produz, e a observabilidade rende mais quando seus dados alimentam a avaliação.
+
+### Camada de controle — delimita o ciclo
+Limitam a autoridade e defendem o sistema.
+
+- **Governança (HRN-008):** codifica política, fluxos de aprovação, prestação de contas e auditabilidade como controles aplicados: portas com humano no ciclo, políticas de ações permitidas e registros de quem ou o quê autorizou cada ação. Responde a “isto é permitido, e quem responde?”.
+- **Segurança (HRN-011):** trata o modelo e suas entradas como não confiáveis: defesa contra injeção de prompts, isolamento de ferramentas, credenciais de privilégio mínimo, validação de saídas e controles de exfiltração de dados. Responde a “pode um adversário fazer este sistema fazer algo que não deve?”.
+
+### Como os componentes se compõem
+Um pedido entra por **planejamento**, que entrega um plano à **orquestração**. A orquestração monta o contexto a partir da **memória**, chama o **modelo** e encaminha as ações escolhidas para as **ferramentas**. Ao longo de todo o processo, a **observabilidade** regista cada span e a **avaliação** pontua resultados; a **governança** trava as ações de risco e a **segurança** guarda as fronteiras. As interfaces entre componentes são onde a confiabilidade se ganha ou se perde: um contrato descuidado entre memória e orquestração, ou uma chamada do modelo a uma ferramenta sem validação, são uma fonte clássica de falha em produção.
+
+### Como usar a taxonomia
+A taxonomia é também uma **lista de maturidade**. Para cada componente, pergunte: temos isto, é explícito, está testado? Muitos projetos de “agentes” implementam apenas a camada de execução e vão para produção sem observabilidade, avaliação, governança nem segurança: os quatro componentes que distinguem um sistema de uma demonstração. Um harness equilibrado investe nas três camadas.
+
+| Camada | Componente | Responsabilidade principal | Capítulo |
+|--------|------------|----------------------------|----------|
+| Execução | Planejamento e objetivos | Decidir a ação seguinte; replanejar | HRN-009 |
+| Execução | Orquestração | Executar o ciclo; encaminhar; orçamentar | HRN-010 |
+| Execução | Memória | Controlar o contexto; recuperar; esquecer | HRN-005 |
+| Execução | Ferramentas / atuação | Agir sobre o mundo através de contratos | HRN-003 |
+| Transversal | Observabilidade | Rastrear, registar, contabilizar, reproduzir | HRN-006 |
+| Transversal | Avaliação | Medir qualidade; travar regressões | HRN-007 |
+| Controle | Governança | Aplicar política; aprovações; auditoria | HRN-008 |
+| Controle | Segurança | Defender contra adversários | HRN-011 |
+
+## Modos de falha observados
+- **Camadas faltando:** implementar apenas a camada de execução (um ciclo que funciona) e omitir observabilidade, avaliação, governança e segurança: o precipício da demonstração para produção.
+- **Acoplamento de componentes:** diluir responsabilidades (por exemplo, a orquestração comprimindo memória em silêncio) de modo que as falhas não possam ser isoladas nem testadas.
+- **Interfaces frágeis:** contratos sem validação nem tipagem entre componentes, sobretudo modelo→ferramenta e recuperação→contexto, que propagam dados maus por todo o ciclo.
+- **Excesso de orquestração:** construir topologias multiagente elaboradas antes de os componentes de um único agente serem confiáveis individualmente.
+
+## KPIs
+| Métrica | Objetivo | Notas |
+|---------|----------|-------|
+| Cobertura de componentes | 8/8 abordados | Cada componente implementado conscientemente ou deixado no mínimo de forma deliberada |
+| Taxa de validação de interfaces | 100 % das chamadas modelo→ferramenta | Evita propagar argumentos malformados ou alucinados |
+| Taxa de conclusão de tarefa | Depende do domínio | Medida pela avaliação (HRN-007) |
+
+## Métricas de custo
+O custo se concentra na camada de execução (inferência e chamadas a ferramentas) e no armazenamento de observabilidade (o volume de traços escala com os passos). A avaliação acrescenta custo periódico por lotes. Governança e segurança são sobretudo custo fixo de engenharia. Uma heurística útil de orçamento é atribuir o custo *por componente*, para que a otimização aponte ao verdadeiro motor da despesa e não ao mais visível.
+
+## Características de escalabilidade
+Cada componente escala por um eixo diferente: a orquestração com a concorrência, a memória com o estado retido e o tamanho do corpus, a observabilidade com os passos por execução, e a avaliação com o tamanho do corpus e as chamadas ao juiz. Como escalam de forma independente, a taxonomia é também uma ferramenta de planejamento de capacidade: os gargalos aparecem em componentes concretos, não “no agente” em abstrato.
+
+## Conteúdo relacionado
+- HRN-001 — Engenharia de Harness: definição e panorama
+- HRN-005 — Memória em sistemas agênticos
+- HRN-006 — Observabilidade para sistemas agênticos
+- HRN-009 — Planejamento e gestão de objetivos
+- HRN-010 — Orquestração
+
+## Referências
+- Literatura de prática sobre arquiteturas de agentes e decomposição em componentes.
+- Observação da indústria sobre a estrutura de sistemas agênticos em produção, 2023–2026.
+- Santa María, S. — Notas de trabalho sobre a taxonomia do harness.
+
+## Perguntas frequentes
+**P:** Por que oito componentes e não mais ou menos?
+**R:** Oito é o conjunto mínimo que cobre executar o ciclo, medi-lo e delimitá-lo sem sobreposição. Pode subdividir (por exemplo, separar ferramentas de atuação), mas as responsabilidades se mantêm.
+
+**P:** O modelo é um componente do harness?
+**R:** O modelo é *invocado pelo* harness e se situa dentro da camada de execução, mas não faz parte do harness: o harness é precisamente tudo o que o rodeia.
+
+**P:** Um sistema pequeno pode saltar a camada de controle?
+**R:** Para um brinquedo, sim; para um sistema empresarial, não. Governança e segurança são o que torna seguro colocar o sistema perante clientes, reguladores e adversários. Podem ser mínimas, mas têm de ser conscientes.

package/content/harness/HRN-004-harness-engineering-principles.es.md

@@ -0,0 +1,91 @@
+---
+title: "Principios de Ingeniería de Harness"
+summary: "Los principios de ingeniería que se sostienen en todos los componentes del harness: frontera de determinismo, autoridad acotada, degradación elegante y medición antes que optimización."
+---
+
+# Principios de Ingeniería de Harness
+
+## Resumen ejecutivo
+Los componentes responden a *qué* contiene un harness; los principios responden a *cómo* construir bien cada uno. Este capítulo enuncia los principios de ingeniería transversales de la Ingeniería de Harness: las reglas que valen tanto si diseñas memoria, como orquestación, como el contrato de una herramienta. Son deliberadamente opinables: un principio que se dobla ante cualquier situación no es un principio.
+
+## Conceptos clave
+- **Principio:** una regla de diseño duradera que guía decisiones en todos los componentes.
+- **Frontera de determinismo:** la línea explícita entre lo que decide el modelo y lo que decide el código.
+- **Evidencia primero:** ninguna afirmación de calidad sin medición.
+- **Defensa en profundidad:** varias capas independientes para que ningún fallo aislado sea catastrófico.
+- **Mínima autoridad:** cada componente recibe el permiso mínimo necesario.
+- **Degradación elegante:** el sistema cae a un modo seguro y reducido en lugar de derrumbarse.
+
+## Definición
+Los **principios de Ingeniería de Harness** son un conjunto de reglas de diseño transversales que gobiernan cómo se construyen y componen los componentes de un harness para que el sistema agéntico resultante sea fiable, observable, gobernable y seguro. Son el equivalente en esta disciplina a los principios SOLID o a la aplicación de doce factores: no un marco de trabajo, sino una postura.
+
+## Explicación detallada
+
+### 1. Fiabilidad por encima de capacidad
+El harness optimiza el *suelo* del comportamiento, no el techo. Un sistema brillante el 95 % del tiempo y catastrófico el 5 % restante es, en una empresa, un pasivo: ese 5 % es lo que sale en la prensa y en la auditoría. Prefiere un alcance más estrecho ejecutado con fiabilidad a uno amplio ejecutado de forma errática. La capacidad la aporta el modelo; la fiabilidad la aporta el harness, y es la que la empresa está pagando.
+
+### 2. Fronteras de determinismo
+Decide explícitamente qué puede decidir el modelo. Todo lo que *pueda* ser determinista *debe* serlo: validación de esquemas, enrutado, comprobación de permisos, reintentos y postcondiciones van en código, no en un prompt. El modelo se reserva para el razonamiento genuinamente abierto que solo él puede hacer. Trazar esta frontera con firmeza es la decisión de mayor apalancamiento en el diseño de un harness: encoge la superficie sobre la que el no determinismo puede hacer daño.
+
+### 3. Observabilidad primero
+Instrumenta antes de optimizar. No puedes depurar, evaluar ni confiar en un sistema no determinista de varios pasos que no puedes ver. Cada llamada al modelo, cada invocación de herramienta y cada decisión deben ser un span estructurado, trazable y reproducible *antes* de dar la funcionalidad por terminada (HRN-006). La observabilidad no es un añadido de segunda fase: es precondición de todos los demás principios, porque todos dependen de la medición.
+
+### 4. Evidencia primero
+Ninguna afirmación de calidad se despliega sin medición. «Parece mejor» no es una afirmación de ingeniería. Los cambios pasan por evaluación contra conjuntos dorados y suites de regresión (HRN-007), y toda afirmación con consecuencias lleva su procedencia (el modelo de evidencia que usa esta misma base de conocimiento). La evidencia primero es lo que convierte el desarrollo de agentes de artesanía en ingeniería.
+
+### 5. Defensa en profundidad
+Asume que cualquier capa aislada fallará —el modelo alucinará, una herramienta devolverá basura, un usuario inyectará un prompt malicioso— y garantiza que ningún fallo suelto sea catastrófico. Superpón controles independientes: validación de entrada *y* de salida *y* puertas de permiso *y* monitorización. El modelo es un componente no confiable: trata su salida como tratarías una entrada de usuario sin validar (HRN-011).
+
+### 6. Mínima autoridad
+Cada componente y cada herramienta recibe la autoridad mínima que su trabajo exige, y ni una más. Solo lectura por defecto; acceso de escritura acotado y con puerta; acciones destructivas tras aprobación humana (controles de la clase PAT-001). El radio de daño de un agente comprometido o confundido está acotado por la autoridad que le concediste: concede poca.
+
+### 7. Degradación elegante
+Cuando algo falla, falla *hacia* un modo seguro y reducido —escala a un humano, devuelve una respuesta conservadora o declina— en lugar de romperse o, peor, tomar con confianza una acción equivocada. El harness debe tener comportamiento bien definido para el bloqueo, el agotamiento de presupuesto, la caída de una herramienta y la baja confianza. Un sistema que no sabe rendirse con seguridad no está listo para producción.
+
+### 8. Actuación idempotente y reversible
+Como el bucle es estocástico y puede reintentar, las acciones sobre el mundo deben ser idempotentes cuando sea posible y reversibles cuando no. Una llamada reintentada no puede cobrar dos veces a un cliente; una escritura debe poder repetirse sin daño; las acciones de alto impacto deben ser preparadas, confirmables y revertibles. Este principio es lo que hace seguros los reintentos, que son imprescindibles para la fiabilidad.
+
+### Tensiones entre principios
+Los principios no siempre van alineados. La fiabilidad por encima de capacidad limita lo que el modelo puede intentar; la observabilidad primero añade latencia y coste; la mínima autoridad frena el desarrollo. La buena ingeniería de harness es el arte de resolver esas tensiones *deliberadamente* y documentar el compromiso, en lugar de dejar que un principio gane en silencio. El metaprincipio: **haz el compromiso explícito y medible.**
+
+| Principio | Riesgo que mitiga | Coste que impone |
+|-----------|-------------------|------------------|
+| Fiabilidad sobre capacidad | Comportamiento catastrófico de cola | Alcance reducido |
+| Fronteras de determinismo | No determinismo sin límites | Esfuerzo de diseño inicial |
+| Observabilidad primero | Ejecuciones indepurables | Almacenamiento, latencia |
+| Evidencia primero | Regresiones silenciosas | Infraestructura de evaluación |
+| Defensa en profundidad | Catástrofe por punto único | Controles redundantes |
+| Mínima autoridad | Radio de daño amplio | Iteración más lenta |
+| Degradación elegante | Acciones erróneas con confianza | Caminos de reserva adicionales |
+| Actuación idempotente | Reintentos dañinos | Complejidad al diseñar acciones |
+
+## Modos de fallo observados
+- **Teatro de principios:** citarlos en un documento de diseño sin exigirlos en el código ni en CI.
+- **Persecución de capacidades:** dejar que una capacidad llamativa del modelo amplíe el alcance más allá de lo que el harness puede controlar con fiabilidad.
+- **Optimizar lo invisible:** ajustar prompts y cadenas antes de que exista observabilidad, de modo que las «mejoras» no están medidas.
+- **Fallo de todo o nada:** sin modo degradado, la caída de un solo componente tumba el sistema entero o produce un error dicho con seguridad.
+
+## Métricas de coste
+Los principios cambian coste marginal por petición (instrumentación, validación, comprobaciones redundantes) por reducciones grandes del coste del fallo (incidentes, retrabajo, hallazgos de auditoría, daño reputacional). El encuadre económicamente correcto es el *coste esperado incluyendo eventos de cola*, donde los principios se pagan solos de forma sistemática.
+
+## Características de escalado
+Los principios componen a escala. Las fronteras de determinismo y la mínima autoridad acotan la superficie de fallo a medida que crecen los pasos y la concurrencia; observabilidad y evidencia primero mantienen depurable y protegido de regresiones un sistema que crece. Los sistemas construidos sin los principios tienden a degradarse de forma superlineal al escalar, porque cada capacidad nueva añade superficie sin límites, sin medir y con exceso de privilegios.
+
+## Contenido relacionado
+- HRN-001 — Ingeniería de Harness: definición y panorama
+- HRN-003 — La taxonomía del harness
+
+## Referencias
+- Analogía con principios de software establecidos (SOLID, doce factores, defensa en profundidad) adaptados a sistemas agénticos.
+- Observación de industria sobre prácticas de fiabilidad en sistemas agénticos, 2023–2026.
+- Santa María, S. — Notas de trabajo sobre principios de diseño de harness.
+
+## Preguntas frecuentes
+**P:** ¿Qué principio importa más?
+**R:** La observabilidad primero es la puerta de entrada práctica, porque todos los demás dependen de la medición. Las fronteras de determinismo son la decisión de diseño con más apalancamiento. Se refuerzan mutuamente.
+
+**P:** ¿No son simplemente principios generales de ingeniería del software?
+**R:** Varios están adaptados de la ingeniería clásica, y es intencionado: los sistemas agénticos siguen siendo software. Pero la frontera de determinismo, medir con evidencia un sistema estocástico y tratar al modelo como entrada no confiable son específicos del harness.
+
+**P:** ¿Cómo se exigen los principios, en vez de solo enunciarlos?
+**R:** Codifícalos en CI y en tiempo de ejecución: validación de esquemas como código, puertas de evaluación al fusionar, comprobación de permisos en la frontera de la herramienta y trazado obligatorio. Un principio que no se exige es un deseo.

package/content/harness/HRN-004-harness-engineering-principles.md

@@ -0,0 +1,135 @@
+---
+id: HRN-004
+title: Harness Engineering Principles
+domain: Harness
+category: Foundations
+status: Draft
+author: Santiago Santa María
+created: 2026-06-21
+updated: 2026-06-21
+summary: The core engineering principles of the harness — reliability over capability, determinism boundaries, observability-first, evidence-first, defense in depth, least authority, graceful degradation, and idempotent actuation — that hold across every component.
+evidence_level: theoretical
+confidence_level: medium
+source_type:
+  - industry_observation
+  - personal_experience
+related:
+  - HRN-001
+  - HRN-003
+tags:
+  - principles
+  - harness-engineering
+  - foundations
+  - reliability
+  - design
+---
+
+# Harness Engineering Principles
+
+## Executive Summary
+Components answer *what* a harness contains; principles answer *how* to build each one well. This chapter states the cross-cutting engineering principles of Harness Engineering — the rules that hold whether you are designing memory, orchestration, or a tool contract. They are opinionated by design: a principle that bends to every situation is not a principle.
+
+## Key Concepts
+- **Principle:** A durable design rule that guides decisions across components.
+- **Determinism boundary:** The explicit line between model-decided and code-decided behavior.
+- **Evidence-first:** No claim of quality without measurement.
+- **Defense in depth:** Multiple independent layers so no single failure is catastrophic.
+- **Least authority:** Each component gets the minimum permission needed.
+- **Graceful degradation:** The system fails into a safe, reduced mode rather than collapsing.
+
+## Definition
+The **Harness Engineering Principles** are a set of cross-cutting design rules that govern how the components of a harness are built and composed so that the resulting agentic system is reliable, observable, governable, and secure. They are the discipline's equivalent of the SOLID principles or the twelve-factor app — not a framework, but a stance.
+
+## Architecture Diagram
+```mermaid
+flowchart LR
+  subgraph Principles
+    P1[Reliability over Capability]
+    P2[Determinism Boundaries]
+    P3[Observability-First]
+    P4[Evidence-First]
+    P5[Defense in Depth]
+    P6[Least Authority]
+    P7[Graceful Degradation]
+    P8[Idempotent Actuation]
+  end
+  P1 --> SYS[(Dependable Agentic System)]
+  P2 --> SYS
+  P3 --> SYS
+  P4 --> SYS
+  P5 --> SYS
+  P6 --> SYS
+  P7 --> SYS
+  P8 --> SYS
+```
+
+## Detailed Explanation
+
+### 1. Reliability over capability
+The harness optimizes for the *floor* of behavior, not the ceiling. A system that is brilliant 95% of the time and catastrophic 5% of the time is, in an enterprise, a liability — the 5% is what makes the news and the audit. Prefer a narrower scope executed dependably to a broad scope executed erratically. Capability is the model's contribution; reliability is the harness's, and it is the one the enterprise is paying for.
+
+### 2. Determinism boundaries
+Decide explicitly what the model is allowed to decide. Everything that *can* be deterministic *should* be: schema validation, routing, permission checks, retries, and post-conditions belong in code, not in a prompt. The model is reserved for the genuinely open-ended reasoning that only it can do. Drawing this boundary tightly is the single highest-leverage move in harness design — it shrinks the surface over which non-determinism can cause harm.
+
+### 3. Observability-first
+Instrument before you optimize. You cannot debug, evaluate, or trust a non-deterministic multi-step system you cannot see. Every model call, tool invocation, and decision should be a structured, traceable, replayable span *before* the feature is considered complete (HRN-006). Observability is not a phase-two add-on; it is a precondition for every other principle, because each of them depends on measurement.
+
+### 4. Evidence-first
+No quality claim ships without measurement. "It seems better" is not an engineering statement. Changes are gated by evaluation against golden sets and regression suites (HRN-007), and every consequential claim carries its provenance (the evidence model this very knowledge base uses). Evidence-first is what converts agent development from craft to engineering.
+
+### 5. Defense in depth
+Assume any single layer will fail — the model will hallucinate, a tool will return garbage, a user will inject a malicious prompt — and ensure no single failure is catastrophic. Layer independent controls: input validation *and* output validation *and* permission gates *and* monitoring. The model is an untrusted component; treat its output as you would treat unvalidated user input (HRN-011).
+
+### 6. Least authority
+Every component and tool receives the minimum authority required for its job and no more. Read-only by default; write access scoped and gated; destructive actions behind human approval (PAT-001-class controls). The blast radius of a compromised or confused agent is bounded by the authority you granted it — so grant little.
+
+### 7. Graceful degradation
+When something fails, fail *into* a safe, reduced mode — escalate to a human, return a conservative answer, or decline — rather than crashing or, worse, taking a confident wrong action. The harness must have well-defined behavior for impasse, budget exhaustion, tool outage, and low confidence. A system that does not know how to give up safely is not production-ready.
+
+### 8. Idempotent and reversible actuation
+Because the loop is stochastic and may retry, actions on the world should be idempotent where possible and reversible where not. A retried tool call must not double-charge a customer; a write should be safe to repeat; high-impact actions should be staged, confirmable, and rollback-capable. This principle is what makes retries — essential for reliability — safe.
+
+### Tensions between principles
+The principles are not always aligned. Reliability-over-capability constrains what the model is allowed to attempt; observability-first adds latency and cost; least-authority slows development. Good harness engineering is the art of resolving these tensions *deliberately* and documenting the trade-off, rather than letting one principle silently win. The meta-principle: **make the trade-off explicit and measurable.**
+
+| Principle | Primary risk it mitigates | Main cost it imposes |
+|-----------|---------------------------|----------------------|
+| Reliability over capability | Catastrophic tail behavior | Reduced scope |
+| Determinism boundaries | Unbounded non-determinism | Up-front design effort |
+| Observability-first | Undebuggable runs | Storage, latency |
+| Evidence-first | Silent regressions | Eval infrastructure |
+| Defense in depth | Single-point catastrophe | Redundant controls |
+| Least authority | Large blast radius | Slower iteration |
+| Graceful degradation | Confident wrong actions | Extra fallback paths |
+| Idempotent actuation | Harmful retries | Action design complexity |
+
+## Observed Failure Modes
+- **Principle theater:** Citing the principles in a design doc but not enforcing them in code or CI.
+- **Capability chasing:** Letting an impressive model capability widen scope past what the harness can reliably control.
+- **Optimizing the unseen:** Tuning prompts and chains before observability exists, so "improvements" are unmeasured.
+- **All-or-nothing failure:** No degraded mode, so any single component outage takes the whole system down or produces a confident error.
+
+## Cost Metrics
+The principles trade marginal per-request cost (instrumentation, validation, redundant checks) for large reductions in the cost of failure (incidents, rework, audit findings, reputational damage). The economically correct framing is *expected cost including tail events*, where the principles consistently pay for themselves.
+
+## Scaling Characteristics
+Principles compound at scale. Determinism boundaries and least authority bound the failure surface as step count and concurrency grow; observability- and evidence-first keep a growing system debuggable and regression-safe. Systems built without the principles tend to degrade super-linearly as they scale, because every new capability adds unbounded, unmeasured, over-privileged surface.
+
+## Related Content
+- HRN-001 — Harness Engineering: Definition and Overview
+- HRN-003 — The Harness Taxonomy
+
+## References
+- Analogy to established software principles (SOLID, twelve-factor, defense in depth) adapted to agentic systems.
+- Industry observation on agentic system reliability practices, 2023–2026.
+- Santa María, S. — Working notes on harness design principles.
+
+## FAQs
+**Q:** Which principle matters most?
+**A:** Observability-first is the practical entry point because every other principle depends on measurement. Determinism boundaries is the highest-leverage design decision. They reinforce each other.
+
+**Q:** Aren't these just general software engineering principles?
+**A:** Several are adapted from classic engineering, which is intentional — agentic systems are still software. But the determinism boundary, evidence-first measurement of a stochastic system, and treating the model as untrusted input are specific to the harness.
+
+**Q:** How do I enforce principles, not just state them?
+**A:** Encode them in CI and runtime: schema validation as code, eval gates on merge, permission checks at the tool boundary, and required tracing. A principle that is not enforced is a wish.

package/content/harness/HRN-004-harness-engineering-principles.pt.md

@@ -0,0 +1,91 @@
+---
+title: "Princípios de Engenharia de Harness"
+summary: "Os princípios de engenharia que se sustentam em todos os componentes do harness: fronteira de determinismo, autoridade limitada, degradação graciosa e medição antes da otimização."
+---
+
+# Princípios de Engenharia de Harness
+
+## Resumo executivo
+Os componentes respondem a *o que* um harness contém; os princípios respondem a *como* construir bem cada um. Este capítulo enuncia os princípios de engenharia transversais da Engenharia de Harness: as regras que valem tanto se estiver desenhando memória, como orquestração, como o contrato de uma ferramenta. São deliberadamente opinativos: um princípio que se dobra a qualquer situação não é um princípio.
+
+## Conceitos-chave
+- **Princípio:** uma regra de desenho duradoura que orienta decisões em todos os componentes.
+- **Fronteira de determinismo:** a linha explícita entre o que o modelo decide e o que o código decide.
+- **Evidência primeiro:** nenhuma afirmação de qualidade sem medição.
+- **Defesa em profundidade:** várias camadas independentes para que nenhuma falha isolada seja catastrófica.
+- **Autoridade mínima:** cada componente recebe a permissão mínima necessária.
+- **Degradação graciosa:** o sistema cai para um modo seguro e reduzido em vez de colapsar.
+
+## Definição
+Os **princípios de Engenharia de Harness** são um conjunto de regras de desenho transversais que governam como os componentes de um harness são construídos e compostos para que o sistema agêntico resultante seja confiável, observável, governável e seguro. São o equivalente nesta disciplina aos princípios SOLID ou à aplicação de doze fatores: não um framework, mas uma postura.
+
+## Explicação detalhada
+
+### 1. Confiabilidade acima de capacidade
+O harness otimiza o *chão* do comportamento, não o teto. Um sistema brilhante em 95 % do tempo e catastrófico nos restantes 5 % é, numa empresa, um passivo: esses 5 % são o que sai na imprensa e na auditoria. Prefira um âmbito mais estreito executado com confiabilidade a um âmbito amplo executado de forma errática. A capacidade é o contributo do modelo; a confiabilidade é a do harness, e é essa que a empresa está pagando.
+
+### 2. Fronteiras de determinismo
+Decida explicitamente o que o modelo pode decidir. Tudo o que *pode* ser determinístico *deve* sê-lo: validação de esquemas, encaminhamento, verificação de permissões, retentativas e pós-condições pertencem ao código, não a um prompt. O modelo se reserva para o raciocínio genuinamente aberto que só ele consegue fazer. Traçar esta fronteira com firmeza é a decisão de maior alavancagem no desenho de um harness: encolhe a superfície sobre a qual o não determinismo pode causar dano.
+
+### 3. Observabilidade primeiro
+Instrumente antes de otimizar. Não consegue depurar, avaliar nem confiar num sistema não determinístico de vários passos que não consegue ver. Cada chamada ao modelo, cada invocação de ferramenta e cada decisão devem ser um span estruturado, rastreável e reproduzível *antes* de a funcionalidade ser dada por concluída (HRN-006). A observabilidade não é um extra de segunda fase: é precondição de todos os outros princípios, porque todos dependem de medição.
+
+### 4. Evidência primeiro
+Nenhuma afirmação de qualidade é lançada sem medição. “Parece melhor” não é uma afirmação de engenharia. As alterações passam por avaliação contra conjuntos dourados e suites de regressão (HRN-007), e toda a afirmação com consequências traz sua proveniência (o modelo de evidência que esta mesma base de conhecimento usa). A evidência primeiro é o que converte o desenvolvimento de agentes de artesanato em engenharia.
+
+### 5. Defesa em profundidade
+Assuma que qualquer camada isolada falhará — o modelo alucinará, uma ferramenta devolverá lixo, um usuário injetará um prompt malicioso — e garanta que nenhuma falha isolada é catastrófica. Sobreponha controles independentes: validação de entrada *e* de saída *e* portas de permissão *e* monitoramento. O modelo é um componente não confiável: trate sua saída como trataria uma entrada de usuário sem validação (HRN-011).
+
+### 6. Autoridade mínima
+Cada componente e cada ferramenta recebe a autoridade mínima que seu trabalho exige, e nem mais. Apenas leitura por padrão; acesso de escrita delimitado e com porta; ações destrutivas atrás de aprovação humana (controles da classe PAT-001). O raio de dano de um agente comprometido ou confuso está limitado pela autoridade que lhe concedeu: conceda pouca.
+
+### 7. Degradação graciosa
+Quando algo falha, falhe *para* um modo seguro e reduzido — escale para um humano, devolva uma resposta conservadora ou recuse — em vez de quebrar ou, pior, tomar com confiança uma ação errada. O harness tem de ter comportamento bem definido para o impasse, o esgotamento de orçamento, a indisponibilidade de uma ferramenta e a baixa confiança. Um sistema que não sabe desistir com segurança não está pronto para produção.
+
+### 8. Atuação idempotente e reversível
+Como o ciclo é estocástico e pode repetir, as ações sobre o mundo devem ser idempotentes quando possível e reversíveis quando não. Uma chamada repetida não pode cobrar duas vezes a um cliente; uma escrita deve poder repetir-se sem dano; as ações de alto impacto devem ser preparadas, confirmáveis e reversíveis. Este princípio é o que torna seguras as retentativas, que são imprescindíveis para a confiabilidade.
+
+### Tensões entre princípios
+Os princípios nem sempre estão alinhados. A confiabilidade acima de capacidade limita o que o modelo pode tentar; a observabilidade primeiro acrescenta latência e custo; a autoridade mínima trava o desenvolvimento. A boa engenharia de harness é a arte de resolver essas tensões *deliberadamente* e documentar o compromisso, em vez de deixar um princípio vencer em silêncio. O metaprincípio: **torne o compromisso explícito e mensurável.**
+
+| Princípio | Risco que mitiga | Custo que impõe |
+|-----------|------------------|-----------------|
+| Confiabilidade acima de capacidade | Comportamento catastrófico de cauda | Âmbito reduzido |
+| Fronteiras de determinismo | Não determinismo sem limites | Esforço de desenho inicial |
+| Observabilidade primeiro | Execuções indepuráveis | Armazenamento, latência |
+| Evidência primeiro | Regressões silenciosas | Infraestrutura de avaliação |
+| Defesa em profundidade | Catástrofe por ponto único | Controles redundantes |
+| Autoridade mínima | Raio de dano amplo | Iteração mais lenta |
+| Degradação graciosa | Ações erradas com confiança | Caminhos de recurso adicionais |
+| Atuação idempotente | Retentativas danosas | Complexidade ao desenhar ações |
+
+## Modos de falha observados
+- **Teatro de princípios:** citá-los num documento de desenho sem os exigir no código nem no CI.
+- **Perseguição de capacidades:** deixar que uma capacidade vistosa do modelo alargue o âmbito para além do que o harness consegue controlar com confiabilidade.
+- **Otimizar o invisível:** afinar prompts e cadeias antes de existir observabilidade, de modo que as “melhorias” não estão medidas.
+- **Falha de tudo ou nada:** sem modo degradado, a queda de um único componente derruba o sistema inteiro ou produz um erro dito com segurança.
+
+## Métricas de custo
+Os princípios trocam custo marginal por pedido (instrumentação, validação, verificações redundantes) por grandes reduções do custo da falha (incidentes, retrabalho, achados de auditoria, dano reputacional). O enquadramento economicamente correto é o *custo esperado incluindo eventos de cauda*, onde os princípios se pagam sistematicamente.
+
+## Características de escalabilidade
+Os princípios compõem à escala. As fronteiras de determinismo e a autoridade mínima delimitam a superfície de falha à medida que crescem os passos e a concorrência; observabilidade e evidência primeiro mantêm depurável e protegido de regressões um sistema que cresce. Os sistemas construídos sem os princípios tendem a degradar-se de forma superlinear ao escalar, porque cada nova capacidade acrescenta superfície sem limites, sem medição e com excesso de privilégios.
+
+## Conteúdo relacionado
+- HRN-001 — Engenharia de Harness: definição e panorama
+- HRN-003 — A taxonomia do harness
+
+## Referências
+- Analogia com princípios de software estabelecidos (SOLID, doze fatores, defesa em profundidade) adaptados a sistemas agênticos.
+- Observação da indústria sobre práticas de confiabilidade em sistemas agênticos, 2023–2026.
+- Santa María, S. — Notas de trabalho sobre princípios de desenho de harness.
+
+## Perguntas frequentes
+**P:** Que princípio importa mais?
+**R:** A observabilidade primeiro é a porta de entrada prática, porque todos os outros dependem da medição. As fronteiras de determinismo são a decisão de desenho com mais alavancagem. Reforçam-se mutuamente.
+
+**P:** Não são simplesmente princípios gerais de engenharia de software?
+**R:** Vários são adaptados da engenharia clássica, e isso é intencional: os sistemas agênticos continuam a ser software. Mas a fronteira de determinismo, medir com evidência um sistema estocástico e tratar o modelo como entrada não confiável são específicos do harness.
+
+**P:** Como se exigem os princípios, em vez de apenas os enunciar?
+**R:** Codifique-os no CI e em tempo de execução: validação de esquemas como código, portas de avaliação na fusão, verificação de permissões na fronteira da ferramenta e rastreio obrigatório. Um princípio que não é exigido é um desejo.

package/content/harness/HRN-005-memory-in-agentic-systems.es.md

@@ -0,0 +1,98 @@
+---
+title: "Memoria en sistemas agénticos"
+summary: "Qué ve el modelo y qué no: recuperación, compresión de contexto, memoria de trabajo y de largo plazo, y las decisiones de olvido que determinan coste y calidad."
+---
+
+# Memoria en sistemas agénticos
+
+## Resumen ejecutivo
+La memoria es el componente del harness que decide qué ve el modelo en cada llamada y qué persiste entre llamadas. Como el modelo no tiene estado y su ventana de contexto es un presupuesto duro y caro, la memoria no es una funcionalidad de base de datos añadida al final: es un sistema de curación activo y con criterio. Este capítulo cubre la jerarquía de memoria (de trabajo, de corto plazo, de largo plazo), la ventana de contexto como restricción determinante y las tres operaciones que hacen tratable la memoria a escala: recuperación, compresión y olvido.
+
+## Conceptos clave
+- **Memoria de trabajo:** el contexto inmediato sobre el que el modelo está razonando ahora mismo, es decir, el prompt ensamblado del paso actual.
+- **Memoria de corto plazo:** el estado acumulado de la tarea o sesión en curso (conversación, resultados intermedios, cuaderno de notas).
+- **Memoria de largo plazo:** conocimiento persistente entre sesiones: preferencias de usuario, resultados previos, hechos de la organización.
+- **Ventana de contexto:** el presupuesto fijo de tokens de una única llamada al modelo; el recurso más escaso del bucle.
+- **Recuperación:** seleccionar los elementos relevantes de un almacén mayor para ponerlos en el contexto.
+- **Compresión:** reducir la huella en tokens de una información conservando su contenido útil (resumen, destilado).
+- **Olvido:** descartar o restar peso deliberadamente a información para controlar coste, relevancia y obsolescencia.
+
+## Definición
+La **memoria en un sistema agéntico** es el subsistema del harness que gestiona el ciclo de vida de la información que el modelo utiliza —su adquisición, almacenamiento, selección hacia el contexto, compresión y eliminación— a lo largo de los horizontes temporales de un paso, de una tarea y de la vida entera del sistema. Su función es poner la información *correcta* en el contexto limitado del modelo en el momento *correcto*, y nada más.
+
+## Explicación detallada
+
+### La ventana de contexto es un presupuesto, no un contenedor
+El hecho más importante sobre la memoria es que la ventana de contexto es *finita y cara*, y que la calidad se degrada a medida que se llena. Incluso con ventanas grandes, meterlo todo eleva coste y latencia y diluye la atención del modelo sobre lo que importa (el efecto «perdido en el medio»). La ingeniería de memoria es, por tanto, un problema de *presupuestación*: cada token gastado en historial o contexto recuperado es un token que no se gasta razonando. El harness debe decidir continuamente qué se gana su sitio en la ventana.
+
+### La jerarquía de memoria
+- La **memoria de trabajo** es lo que hay en la ventana de contexto para la llamada actual. Se ensambla de nuevo en cada paso a partir de los demás niveles.
+- La **memoria de corto plazo** guarda el estado en evolución de la tarea en curso: la conversación hasta el momento, los resultados de herramientas y un cuaderno de razonamiento intermedio. Crece de forma monótona si no se gestiona, y por eso es el objetivo principal de la compresión y el olvido.
+- La **memoria de largo plazo** persiste entre tareas y sesiones: almacenes semánticos (a menudo indexados vectorialmente para recuperación por similitud), perfiles y hechos estructurados (clave-valor o relacionales), y registros episódicos de resultados de tareas pasadas de los que el agente puede aprender. La memoria de largo plazo es lo que permite a un agente ser *consistente* entre sesiones y *mejorar* con el tiempo.
+
+### Recuperación: elegir qué sacar a la superficie
+La recuperación selecciona elementos relevantes de la memoria de largo plazo (y a veces de la de corto plazo) para inyectarlos en la memoria de trabajo. El enfoque dominante es la similitud semántica sobre embeddings, con frecuencia complementada con búsqueda léxica por palabras clave (recuperación híbrida) y reordenación. La calidad de la recuperación domina la calidad de la respuesta: un contexto irrelevante o ausente no se arregla con un prompt mejor. Entre los refinamientos habituales están la reescritura de consultas, el filtrado por metadatos y la ponderación por recencia o autoridad. Patrones como PAT-006 (recuperación de conocimiento) formalizan estas decisiones.
+
+### Compresión: caber más dentro del presupuesto
+Cuando la memoria de corto plazo desborda el presupuesto, el harness la comprime. Las técnicas van desde el truncado simple (descartar los turnos más antiguos) al resumen incremental (sustituir los turnos viejos por un resumen acumulado) y a la compresión jerárquica o semántica (resumir a varias granularidades y conservar punteros al detalle). La compresión es, por definición, con pérdida, así que la pregunta de ingeniería es *qué se puede perder sin riesgo*, y eso depende de la tarea. Un agente de programación debe conservar los identificadores exactos; un agente de soporte puede resumir la charla intrascendente con agresividad.
+
+### Olvido: deliberado, no accidental
+El olvido es un control activo, no un fallo. El harness debe descartar información obsoleta (un dato que ha cambiado), irrelevante (contexto fuera de tema) o fuera de presupuesto (desalojo bajo presión). Sin olvido explícito, la memoria de largo plazo acumula contradicciones y ruido, y la de corto plazo se desborda. Las buenas políticas de olvido restan peso por recencia y relevancia, caducan los hechos de volatilidad conocida y resuelven conflictos (gana el valor autorizado más reciente). El olvido es además una superficie de *gobernanza*: los requisitos de retención de datos y de derecho al olvido viven aquí.
+
+### Escritura y consolidación de memoria
+Para cerrar el bucle, el harness decide qué *escribir de vuelta* a memoria tras un paso o una tarea: extraer hechos duraderos, resumir el episodio, actualizar el perfil de usuario. Ese paso de consolidación —análogo a pasar la memoria de trabajo al almacenamiento de largo plazo— es lo que convierte un modelo sin estado en un sistema que acumula conocimiento. Hecho sin cuidado, es también la forma en que un agente envenena su propio contexto futuro con un «hecho» alucinado, y por eso las escrituras deben validarse como cualquier otra actuación.
+
+### La memoria como superficie de ataque
+Todo lo que se escribe en memoria y luego se lee hacia el contexto es un vector de inyección de prompts. Los documentos recuperados y los «hechos» almacenados pueden llevar instrucciones adversarias. La memoria interseca por tanto directamente con la seguridad (HRN-011): trata el contenido recuperado y recordado como entrada no confiable, no como prompt de sistema de confianza.
+
+## 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:** agentes asistentes empresariales de larga duración (soporte, investigación, programación) operando en sesiones de muchos turnos.
+- **Escenario:** la acumulación ingenua del historial completo de conversación en la ventana de contexto dispara coste y latencia y hunde la calidad de respuesta a medida que la sesión se alarga; introducir resumen incremental más recuperación híbrida restaura la calidad a una fracción del coste en tokens.
+- **Tecnología:** LLM frontera, almacén vectorial, recuperador híbrido con reordenación, modelo de resumen para la compresión.
+- **Carga:** sesiones que van de unos pocos turnos a cientos, con almacenes de largo plazo de miles a millones de elementos.
+- **Resultados:** la experiencia representativa es una reducción sustancial de tokens por turno y una mayor consistencia de la tarea en cuanto la memoria se gestiona activamente en lugar de acumularse de forma pasiva.
+
+## Modos de fallo observados
+- **Desbordamiento de contexto:** una memoria de corto plazo sin gestionar excede la ventana y trunca precisamente la información que importaba.
+- **Perdido en el medio:** un contexto sobrecargado degrada la atención al contenido central del prompt; más contexto produce peores respuestas.
+- **Fallo de recuperación:** el documento relevante nunca aflora y el modelo responde con seguridad desde un hueco.
+- **Memoria obsoleta o contradictoria:** el almacén de largo plazo guarda hechos caducados o en conflicto y el agente actúa sobre el equivocado.
+- **Envenenamiento de memoria:** un «hecho» alucinado o adversario se escribe de vuelta y contamina el razonamiento futuro.
+
+## KPIs
+| Métrica | Objetivo | Notas |
+|---------|----------|-------|
+| Precisión / exhaustividad de recuperación | Dependiente del dominio, medida | Calidad de los elementos llevados al contexto |
+| Utilización del contexto | Por debajo de la ventana, con margen | Tokens usados frente al presupuesto por llamada |
+| Tokens por turno | Minimizados a calidad constante | Motor directo de coste |
+| Anclaje de la respuesta | Alto | Proporción de afirmaciones sostenidas por el contexto recuperado |
+
+## Métricas de coste
+La memoria es una palanca de coste de primer orden. Los tokens colocados en contexto se pagan en cada llamada, de modo que la compresión y una recuperación precisa reducen directamente el gasto de inferencia. La memoria de largo plazo añade coste de almacenamiento e indexación por embeddings, y la compresión añade llamadas a un modelo de resumen. El balance es casi siempre favorable: la gestión activa de memoria cambia resumen e indexación baratos por lotes por tokens de contexto caros por llamada.
+
+## Características de escalado
+La memoria escala en dos ejes: longitud de sesión (que gobierna la memoria de corto plazo y la frecuencia de compresión) y tamaño del corpus (que gobierna el almacén de largo plazo y la latencia de recuperación). La latencia y la calidad de recuperación son los cuellos de botella habituales a medida que crece el almacén de largo plazo; el particionado, el filtrado y la reordenación se vuelven necesarios. Y lo esencial: una memoria bien gestionada mantiene *plano* el coste por llamada aunque la sesión se alargue, mientras que la acumulación ingenua lo hace crecer sin límite.
+
+## Contenido relacionado
+- HRN-003 — La taxonomía del harness
+- PAT-004 — (patrón de memoria / contexto)
+- PAT-006 — (patrón de recuperación de conocimiento)
+
+## Referencias
+- Investigación sobre los efectos de la longitud de contexto en los LLM («perdido en el medio»).
+- Literatura de práctica sobre RAG, recuperación híbrida y reordenación.
+- Santa María, S. — Notas de trabajo sobre arquitectura de memoria de agentes.
+
+## Preguntas frecuentes
+**P:** Con ventanas de contexto de un millón de tokens, ¿no queda obsoleta la ingeniería de memoria?
+**R:** No. Las ventanas mayores elevan el presupuesto, pero no lo eliminan: el coste, la latencia y la dilución de atención siguen escalando con lo que metes. Las ventanas grandes hacen la ingeniería de memoria *más* valiosa, no menos, porque la tentación de sobrecargar es mayor.
+
+**P:** ¿La memoria no es simplemente RAG?
+**R:** La recuperación (RAG) es una operación dentro de la memoria. La memoria cubre además el estado de trabajo y de corto plazo, la compresión, el olvido y la consolidación por escritura. RAG sin todo eso está incompleto.
+
+**P:** ¿Debe decidir el modelo qué recordar?
+**R:** En parte. El modelo puede proponer qué consolidar, pero el harness debe validar y gobernar las escrituras: las autoescrituras sin validar son la forma en que los agentes envenenan su propia memoria.