santismm-knowledge-mcp 0.2.1

package/content/harness/HRN-002-a-brief-history-of-harness-engineering.es.md

@@ -0,0 +1,83 @@
+---
+title: "Breve historia de la Ingeniería de Harness"
+summary: "Cómo la industria pasó de la ingeniería de prompts a los sistemas agénticos, y por qué el andamiaje alrededor del modelo acabó siendo la disciplina que decide la fiabilidad."
+---
+
+# Breve historia de la Ingeniería de Harness
+
+## Resumen ejecutivo
+La Ingeniería de Harness no apareció ya formada. Emergió a lo largo de cuatro eras que se solapan: ingeniería de prompts, uso de herramientas, agentes y, por fin, harnesses. Cada era resolvió un problema y dejó al descubierto el siguiente. Este capítulo recorre ese arco, nombra los puntos de inflexión y explica por qué la acumulación de esas lecciones cristalizó en una disciplina cuya unidad de trabajo es el sistema entero, no el prompt.
+
+## Conceptos clave
+- **Ingeniería de prompts:** dar forma a una única interacción con el modelo mediante instrucciones, ejemplos y formato.
+- **Uso de herramientas (function calling):** dotar al modelo de la capacidad de emitir llamadas estructuradas a funciones externas.
+- **Agente:** un modelo que ejecuta un bucle de percibir, razonar y actuar hacia un objetivo, con memoria y herramientas.
+- **Harness:** el andamiaje de ingeniería completo alrededor del modelo que hace fiable al sistema agéntico.
+- **Punto de inflexión:** el momento en que una abstracción anterior deja de escalar y obliga a añadir una capa nueva.
+
+## Definición
+La **historia de la Ingeniería de Harness** es la progresión por la que el foco del esfuerzo de ingeniería se desplazó hacia fuera: del prompt a la interacción con el modelo, luego al bucle y finalmente al sistema entero que rodea al modelo, hasta reconocer que construir ese sistema es una disciplina por derecho propio.
+
+## Explicación detallada
+
+### Era 1 — Ingeniería de prompts (la interacción única)
+La primera ola trató al modelo como un oráculo: redacta el prompt correcto y lee la respuesta. Las técnicas se acumularon deprisa: instrucciones, ejemplos few-shot, encuadre de rol, cadena de pensamiento y formatos de salida rígidos. La ingeniería de prompts era real y útil, pero optimizaba *una sola* llamada al modelo. Su techo llegaba en el momento en que una tarea exigía que el modelo *hiciera* algo en el mundo, o que recordara cualquier cosa más allá de la ventana de contexto. La lección: un prompt mejor no convierte a un oráculo sin estado en un sistema.
+
+### Era 2 — Uso de herramientas (el modelo actúa y recupera)
+La segunda ola le dio manos al modelo. El function calling permitió al modelo emitir peticiones estructuradas que el código circundante ejecutaba: búsqueda, calculadoras, consultas a bases de datos, llamadas a API. La generación aumentada por recuperación (RAG) atacó el problema del conocimiento trayendo el contexto relevante en tiempo de consulta en lugar de confiar en que estuviera memorizado. Fue un cambio arquitectónico genuino: ahora había *código alrededor del modelo* que importaba. Pero seguía siendo en gran medida un solo salto: llamar al modelo, ejecutar una herramienta, devolver el resultado. Los problemas de fiabilidad aparecieron de inmediato: las herramientas fallan, devuelven datos mal formados, expiran o se invocan con argumentos alucinados. La lección: en cuanto el modelo toca sistemas reales hacen falta contratos, validación y gestión de fallos —ingeniería, no prompting—.
+
+### Era 3 — Agentes (el bucle)
+La tercera ola cerró el bucle. En vez de un salto, el modelo iteraba: observar resultados, razonar, volver a actuar, hasta cumplir el objetivo. Aparecieron patrones como los bucles de razonar-y-actuar, los planificadores con herramientas y las descomposiciones multiagente, empaquetados en frameworks populares. Los agentes ya podían reservar un viaje, refactorizar código o triar un ticket a lo largo de muchos pasos. Y aquí afloraron a escala los modos de fallo *de verdad*: bucles que no terminan, errores que se componen cuando un paso malo envenena el resto, coste desbocado, ventanas de contexto desbordadas de historial acumulado, y la imposibilidad de depurar a posteriori una ejecución no determinista de varios pasos. Los frameworks de agentes hicieron el bucle fácil de *escribir* y casi imposible de *operar con fiabilidad*. La lección: un bucle sin disciplina de memoria, observabilidad, evaluación y autoridad acotada es un pasivo, no un producto.
+
+### Era 4 — Harnesses (el sistema)
+La cuarta ola —donde vive hoy la disciplina— es el reconocimiento de que todo lo que rodea al modelo *es el problema de ingeniería*. Los equipos que llevaban agentes a producción empresarial descubrieron que dedicaban casi todo su esfuerzo no al modelo, ni siquiera al bucle del agente, sino a:
+
+- La **memoria** que decide qué ve el modelo y qué olvida (HRN-005);
+- La **observabilidad** que convierte una ejecución opaca en trazas reproducibles (HRN-006);
+- La **evaluación** que transforma «parece que va bien» en calidad medida y protegida frente a regresiones (HRN-007);
+- La **gobernanza** que aplica política y aprobación humana como código;
+- La **seguridad** que trata al modelo como un componente no confiable e inyectable por prompt;
+- La **orquestación** que acota el bucle, enruta el trabajo y degrada con elegancia.
+
+Ese conjunto es el harness. Ponerle nombre importó: reencuadró «he construido un agente» (una demo) como «he construido un harness» (un sistema que puedes poner delante de clientes y auditores). HRN-003 formaliza los componentes como taxonomía.
+
+### Por qué cambiaron los nombres
+Cada renombrado reflejó una ampliación de la unidad de responsabilidad. Prompt → la llamada. Uso de herramientas → la llamada más sus acciones. Agente → el bucle. Harness → el sistema, incluidas las partes que ninguna demo enseña: qué pasa a las tres de la madrugada bajo carga, bajo ataque, bajo auditoría. La historia es, en esencia, la constatación progresiva de que la parte difícil nunca fue el modelo.
+
+## Evidencia de producción
+> **Nivel de evidencia:** teórico · **Confianza:** media · **Fuente:** observación de industria
+>
+> _Relato ilustrativo y representativo, no un despliegue verificado concreto._
+
+- **Contexto:** equipos empresariales que adoptan agentes LLM entre 2023 y 2026.
+- **Escenario:** un equipo entrega una demo de agente impresionante y luego dedica los dos trimestres siguientes no a mejorar el modelo, sino a construir gestión de memoria, trazado, arneses de evaluación, puertas de aprobación y defensas contra inyección de prompts para que sea seguro en producción.
+- **Tecnología:** LLM frontera, API de function calling, almacenes vectoriales, frameworks de agentes, backends de trazado.
+- **Carga:** de un puñado de ejecuciones de demo a tráfico sostenido de producción con usuarios adversarios.
+- **Resultados:** la experiencia representativa es que el harness, y no el modelo, consume la mayor parte del esfuerzo de ingeniería y es lo que en última instancia condiciona el lanzamiento a producción.
+
+## Modos de fallo observados
+- **Equivocarse de era:** tratar un problema de uso de herramientas como un problema de prompt, o un problema de agente como uno de herramientas: aplicar la abstracción de ayer al fallo de hoy.
+- **El framework como estrategia:** dar por hecho que un framework de agentes *es* el harness; los frameworks aportan el bucle, no la observabilidad, la evaluación, la gobernanza ni la seguridad.
+- **Saltar directamente a multiagente:** recurrir a enjambres de agentes elaborados antes de que el harness de un solo agente sea fiable, multiplicando la superficie de fallo.
+
+## Características de escalado
+Cada era empujó el cuello de botella de fiabilidad más hacia fuera. A medida que los sistemas escalaron en pasos y herramientas, la restricción determinante pasó de «¿es bueno el prompt?» a «¿termina el bucle, se mantiene en presupuesto y sigue siendo auditable?», que es precisamente el dominio del harness.
+
+## Contenido relacionado
+- HRN-001 — Ingeniería de Harness: definición y panorama
+- HRN-003 — La taxonomía del harness
+
+## Referencias
+- Observación de industria sobre la evolución de los patrones de aplicación de LLM, 2020–2026.
+- Literatura de práctica sobre RAG, function calling y bucles de agentes.
+- Santa María, S. — Notas de trabajo sobre la aparición de la Ingeniería de Harness.
+
+## Preguntas frecuentes
+**P:** ¿Algún producto o artículo inventó la Ingeniería de Harness?
+**R:** No. Surgió de la experiencia convergente de muchos equipos que chocaron con el mismo muro: los agentes son fáciles de demostrar y difíciles de operar. La disciplina es un nombre para las lecciones, no un artefacto concreto.
+
+**P:** ¿Están obsoletas las eras anteriores?
+**R:** No: quedan subsumidas. El prompting, el uso de herramientas y los bucles de agentes son componentes dentro de un harness moderno. El harness añade las capas que los hacen de fiar.
+
+**P:** ¿Qué viene después de los harnesses?
+**R:** Probablemente estandarización y madurez de utillaje —plataformas de harness compartidas, estándares interoperables de observabilidad y evaluación, y gobernanza integrada en los runtimes— más que un paradigma enteramente nuevo. La unidad de responsabilidad (el sistema) ya es estable.

package/content/harness/HRN-002-a-brief-history-of-harness-engineering.md

@@ -0,0 +1,113 @@
+---
+id: HRN-002
+title: A Brief History of Harness Engineering
+domain: Harness
+category: Foundations
+status: Draft
+author: Santiago Santa María
+created: 2026-06-21
+updated: 2026-06-21
+summary: How the field moved from prompt engineering to tool use to agents to harnesses, and why the engineered scaffolding around the model became its own discipline.
+evidence_level: theoretical
+confidence_level: medium
+source_type:
+  - industry_observation
+  - personal_experience
+related:
+  - HRN-001
+  - HRN-003
+tags:
+  - history
+  - harness-engineering
+  - foundations
+  - agentic-systems
+---
+
+# A Brief History of Harness Engineering
+
+## Executive Summary
+Harness Engineering did not appear fully formed. It emerged over roughly four overlapping eras: prompt engineering, tool use, agents, and finally harnesses. Each era solved a problem and exposed the next one. This chapter traces that arc, names the inflection points, and explains why the accumulation of these lessons crystallized into a discipline whose unit of work is the whole system, not the prompt.
+
+## Key Concepts
+- **Prompt engineering:** Shaping a single model interaction through instructions, examples, and formatting.
+- **Tool use (function calling):** Giving the model the ability to emit structured calls to external functions.
+- **Agent:** A model running a perceive–reason–act loop toward a goal, with memory and tools.
+- **Harness:** The full engineered scaffolding around the model that makes the agentic system reliable.
+- **Inflection point:** A moment where a prior abstraction stopped scaling and forced a new layer.
+
+## Definition
+The **history of Harness Engineering** is the progression by which the locus of engineering effort moved outward from the prompt to the model interaction, then to the loop, and finally to the entire system surrounding the model — culminating in the recognition that building that system is a discipline in its own right.
+
+## Architecture Diagram
+```mermaid
+timeline
+  title Eras of Harness Engineering
+  Prompt Engineering : Single-shot instructions : Few-shot examples : Output formatting
+  Tool Use : Function calling : Structured outputs : Retrieval (RAG)
+  Agents : Reason-act loops : Multi-step planning : Working memory
+  Harnesses : Orchestration & memory : Observability & eval : Governance & security
+```
+
+## Detailed Explanation
+
+### Era 1 — Prompt Engineering (the single interaction)
+The first wave treated the model as an oracle: craft the right prompt and read off the answer. Techniques accreted quickly — instructions, few-shot examples, role framing, chain-of-thought, and rigid output formatting. Prompt engineering was real and useful, but it optimized a *single* model call. Its ceiling was the moment a task required the model to *do* something in the world, or to remember anything beyond the context window. The lesson: a better prompt cannot make a stateless oracle into a system.
+
+### Era 2 — Tool Use (the model acts and retrieves)
+The second wave gave the model hands. Function calling let the model emit structured requests that surrounding code executed — search, calculators, database queries, API calls. Retrieval-augmented generation (RAG) attacked the knowledge problem by fetching relevant context at query time instead of hoping it was memorized. This was a genuine architectural shift: now there was *code around the model* that mattered. But it was still largely a single hop — call the model, run a tool, return the result. Reliability problems emerged immediately: tools fail, return malformed data, time out, or are called with hallucinated arguments. The lesson: the moment the model touches real systems, you need contracts, validation, and failure handling — engineering, not prompting.
+
+### Era 3 — Agents (the loop)
+The third wave closed the loop. Instead of one hop, the model ran iteratively: observe results, reason, act again, until the goal was met. Patterns like reason-and-act loops, tool-using planners, and multi-agent decompositions appeared, packaged in popular frameworks. Agents could now book a trip, refactor code, or triage a ticket across many steps. And here the *real* failure modes surfaced at scale: loops that never terminate, compounding errors where one bad step poisons the rest, runaway cost, context windows overflowing with accumulated history, and the impossibility of debugging a non-deterministic multi-step run after the fact. The agent frameworks made the loop easy to *write* and nearly impossible to *operate reliably*. The lesson: a loop without memory discipline, observability, evaluation, and bounded authority is a liability, not a product.
+
+### Era 4 — Harnesses (the system)
+The fourth wave — where the discipline now lives — is the recognition that everything around the model *is the engineering problem*. Teams putting agents into enterprise production discovered they were spending almost all of their effort not on the model and not even on the agent loop, but on:
+
+- **Memory** that decides what the model sees and what it forgets (HRN-005);
+- **Observability** that turns an opaque run into traceable, replayable spans (HRN-006);
+- **Evaluation** that converts "seems fine" into measured, regression-guarded quality (HRN-007);
+- **Governance** that enforces policy and human approval as code;
+- **Security** that treats the model as an untrusted, prompt-injectable component;
+- **Orchestration** that bounds the loop, routes work, and degrades gracefully.
+
+This collection is the harness. Naming it mattered: it reframed "I built an agent" (a demo) into "I built a harness" (a system you can run in front of customers and auditors). HRN-003 formalizes the components as a taxonomy.
+
+### Why the names changed
+Each rename reflected an expansion of the unit of accountability. Prompt → the call. Tool use → the call plus its actions. Agent → the loop. Harness → the system, including the parts no demo ever shows: what happens at 3 a.m. under load, under attack, under audit. The history is, in essence, the steady realization that the hard part was never the model.
+
+## Production Evidence
+> **Evidence level:** theoretical · **Confidence:** medium · **Source:** industry_observation
+>
+> _Illustrative, representative narrative — not a single verified deployment._
+
+- **Context:** Enterprise teams adopting LLM agents between 2023 and 2026.
+- **Scenario:** A team ships an impressive agent demo, then spends the following two quarters not improving the model but building memory management, tracing, evaluation harnesses, approval gates, and prompt-injection defenses to make it safe for production.
+- **Technology:** Frontier LLMs, function-calling APIs, vector stores, agent frameworks, tracing backends.
+- **Load:** From a handful of demo runs to sustained production traffic with adversarial users.
+- **Results:** Representative experience is that the harness, not the model, consumes the majority of engineering effort and is what ultimately gates the production launch.
+
+## Observed Failure Modes
+- **Mistaking the era:** Treating a tool-use problem as a prompt problem, or an agent problem as a tool problem — applying yesterday's abstraction to today's failure.
+- **Framework lock-in as strategy:** Assuming an agent framework *is* the harness; frameworks provide the loop, not the observability, evaluation, governance, or security.
+- **Skipping straight to multi-agent:** Reaching for elaborate agent swarms before the single-agent harness is reliable, multiplying failure surface.
+
+## Scaling Characteristics
+Each era pushed the reliability bottleneck outward. As systems scaled in steps and tools, the binding constraint moved from "is the prompt good" to "does the loop terminate, stay in budget, and remain auditable" — which is precisely the harness's domain.
+
+## Related Content
+- HRN-001 — Harness Engineering: Definition and Overview
+- HRN-003 — The Harness Taxonomy
+
+## References
+- Industry observation on the evolution of LLM application patterns, 2020–2026.
+- Practitioner literature on RAG, function calling, and agent loops.
+- Santa María, S. — Working notes on the emergence of Harness Engineering.
+
+## FAQs
+**Q:** Did one product or paper invent Harness Engineering?
+**A:** No. It emerged from convergent practitioner experience across many teams hitting the same wall: agents are easy to demo and hard to operate. The discipline is a name for the lessons, not a single artifact.
+
+**Q:** Are the earlier eras obsolete?
+**A:** No — they are subsumed. Prompting, tool use, and agent loops are all components inside a modern harness. The harness adds the layers that make them dependable.
+
+**Q:** What comes after harnesses?
+**A:** Likely standardization and tooling maturity — shared harness platforms, interoperable observability and evaluation standards, and governance baked into runtimes — rather than a wholly new paradigm. The unit of accountability (the system) is now stable.

package/content/harness/HRN-002-a-brief-history-of-harness-engineering.pt.md

@@ -0,0 +1,83 @@
+---
+title: "Breve história da Engenharia de Harness"
+summary: "Como a indústria passou da engenharia de prompts para os sistemas agênticos, e porque o andaime em torno do modelo acabou por ser a disciplina que decide a confiabilidade."
+---
+
+# Breve história da Engenharia de Harness
+
+## Resumo executivo
+A Engenharia de Harness não apareceu já formada. Emergiu ao longo de quatro eras que se sobrepõem: engenharia de prompts, uso de ferramentas, agentes e, por fim, harnesses. Cada era resolveu um problema e deixou a descoberto o seguinte. Este capítulo percorre esse arco, nomeia os pontos de inflexão e explica porque a acumulação dessas lições cristalizou numa disciplina cuja unidade de trabalho é o sistema inteiro, não o prompt.
+
+## Conceitos-chave
+- **Engenharia de prompts:** dar forma a uma única interação com o modelo através de instruções, exemplos e formatação.
+- **Uso de ferramentas (function calling):** dotar o modelo da capacidade de emitir chamadas estruturadas a funções externas.
+- **Agente:** um modelo que executa um ciclo de percecionar, raciocinar e agir rumo a um objetivo, com memória e ferramentas.
+- **Harness:** o andaime de engenharia completo em torno do modelo que torna confiável o sistema agêntico.
+- **Ponto de inflexão:** o momento em que uma abstração anterior deixa de escalar e obriga a acrescentar uma camada nova.
+
+## Definição
+A **história da Engenharia de Harness** é a progressão pela qual o foco do esforço de engenharia se deslocou para fora: do prompt para a interação com o modelo, depois para o ciclo e finalmente para o sistema inteiro que rodeia o modelo, até se reconhecer que construir esse sistema é uma disciplina por direito próprio.
+
+## Explicação detalhada
+
+### Era 1 — Engenharia de prompts (a interação única)
+A primeira vaga tratou o modelo como um oráculo: redija o prompt certo e leia a resposta. As técnicas se acumularam rapidamente: instruções, exemplos few-shot, enquadramento de papel, cadeia de pensamento e formatos de saída rígidos. A engenharia de prompts era real e útil, mas otimizava *uma só* chamada ao modelo. Seu teto chegava no momento em que uma tarefa exigia que o modelo *fizesse* algo no mundo, ou que recordasse seja o que for para além da janela de contexto. A lição: um prompt melhor não converte um oráculo sem estado num sistema.
+
+### Era 2 — Uso de ferramentas (o modelo age e recupera)
+A segunda vaga deu mãos ao modelo. O function calling permitiu ao modelo emitir pedidos estruturados que o código circundante executava: pesquisa, calculadoras, consultas a bases de dados, chamadas a API. A geração aumentada por recuperação (RAG) atacou o problema do conhecimento trazendo o contexto relevante em tempo de consulta em vez de confiar em que estivesse memorizado. Foi uma mudança arquitetônica genuína: passou a haver *código em torno do modelo* que importava. Mas continuava a ser em larga medida um único salto: chamar o modelo, executar uma ferramenta, devolver o resultado. Os problemas de confiabilidade surgiram de imediato: as ferramentas falham, devolvem dados malformados, expiram ou são invocadas com argumentos alucinados. A lição: assim que o modelo toca em sistemas reais são precisos contratos, validação e tratamento de falhas — engenharia, não prompting.
+
+### Era 3 — Agentes (o ciclo)
+A terceira vaga fechou o ciclo. Em vez de um salto, o modelo iterava: observar resultados, raciocinar, voltar a agir, até cumprir o objetivo. Apareceram padrões como os ciclos de raciocinar-e-agir, os planejadores com ferramentas e as decomposições multiagente, empacotados em frameworks populares. Os agentes já conseguiam reservar uma viagem, refatorizar código ou triar um ticket ao longo de muitos passos. E foi aqui que os modos de falha *a sério* afloraram à escala: ciclos que não terminam, erros que se compõem quando um passo mau envenena o resto, custo descontrolado, janelas de contexto transbordadas de histórico acumulado, e a impossibilidade de depurar a posteriori uma execução não determinista de vários passos. As frameworks de agentes tornaram o ciclo fácil de *escrever* e quase impossível de *operar com confiabilidade*. A lição: um ciclo sem disciplina de memória, observabilidade, avaliação e autoridade limitada é um passivo, não um produto.
+
+### Era 4 — Harnesses (o sistema)
+A quarta vaga — onde vive hoje a disciplina — é o reconhecimento de que tudo o que rodeia o modelo *é o problema de engenharia*. As equipes que levavam agentes para produção empresarial descobriram que dedicavam quase todo o seu esforço não ao modelo, nem sequer ao ciclo do agente, mas a:
+
+- A **memória** que decide o que o modelo vê e o que esquece (HRN-005);
+- A **observabilidade** que converte uma execução opaca em traços reproduzíveis (HRN-006);
+- A **avaliação** que transforma “parece que está bem” em qualidade medida e protegida contra regressões (HRN-007);
+- A **governança** que aplica política e aprovação humana como código;
+- A **segurança** que trata o modelo como um componente não confiável e injetável por prompt;
+- A **orquestração** que limita o ciclo, encaminha o trabalho e degrada com elegância.
+
+Esse conjunto é o harness. Dar-lhe nome importou: reenquadrou “construí um agente” (uma demonstração) como “construí um harness” (um sistema que se pode pôr à frente de clientes e auditores). HRN-003 formaliza os componentes como taxonomia.
+
+### Por que mudaram os nomes
+Cada mudança de nome refletiu um alargamento da unidade de responsabilidade. Prompt → a chamada. Uso de ferramentas → a chamada mais suas ações. Agente → o ciclo. Harness → o sistema, incluindo as partes que nenhuma demonstração mostra: o que acontece às três da manhã sob carga, sob ataque, sob auditoria. A história é, no essencial, a constatação progressiva de que a parte difícil nunca foi o modelo.
+
+## Evidência de produção
+> **Nível de evidência:** teórico · **Confiança:** média · **Fonte:** observação de indústria
+>
+> _Relato ilustrativo e representativo, não uma implantação verificada concreta._
+
+- **Contexto:** equipes empresariais que adotam agentes LLM entre 2023 e 2026.
+- **Cenário:** uma equipe entrega uma demonstração de agente impressionante e depois dedica os dois trimestres seguintes não a melhorar o modelo, mas a construir gestão de memória, tracing, harnesses de avaliação, portas de aprovação e defesas contra injeção de prompts para que seja seguro em produção.
+- **Tecnologia:** LLM de fronteira, API de function calling, armazéns vetoriais, frameworks de agentes, backends de tracing.
+- **Carga:** de um punhado de execuções de demonstração a tráfego sustentado de produção com usuários adversários.
+- **Resultados:** a experiência representativa é que o harness, e não o modelo, consome a maior parte do esforço de engenharia e é o que em última instância condiciona o lançamento em produção.
+
+## Modos de falha observados
+- **Enganar-se na era:** tratar um problema de uso de ferramentas como um problema de prompt, ou um problema de agente como um de ferramentas: aplicar a abstração de ontem à falha de hoje.
+- **A framework como estratégia:** assumir que uma framework de agentes *é* o harness; as frameworks fornecem o ciclo, não a observabilidade, a avaliação, a governança nem a segurança.
+- **Saltar diretamente para multiagente:** recorrer a enxames de agentes elaborados antes de o harness de um só agente ser confiável, multiplicando a superfície de falha.
+
+## Características de escalabilidade
+Cada era empurrou o gargalo de confiabilidade mais para fora. À medida que os sistemas escalaram em passos e ferramentas, a restrição determinante passou de “o prompt é bom?” para “o ciclo termina, mantém-se dentro do orçamento e continua auditável?”, que é precisamente o domínio do harness.
+
+## Conteúdo relacionado
+- HRN-001 — Engenharia de Harness: definição e panorama
+- HRN-003 — A taxonomia do harness
+
+## Referências
+- Observação de indústria sobre a evolução dos padrões de aplicação de LLM, 2020–2026.
+- Literatura de prática sobre RAG, function calling e ciclos de agentes.
+- Santa María, S. — Notas de trabalho sobre o aparecimento da Engenharia de Harness.
+
+## Perguntas frequentes
+**P:** Algum produto ou artigo inventou a Engenharia de Harness?
+**R:** Não. Surgiu da experiência convergente de muitas equipes que embateram no mesmo muro: os agentes são fáceis de demonstrar e difíceis de operar. A disciplina é um nome para as lições, não um artefacto concreto.
+
+**P:** As eras anteriores estão obsoletas?
+**R:** Não: ficam subsumidas. O prompting, o uso de ferramentas e os ciclos de agentes são todos componentes dentro de um harness moderno. O harness acrescenta as camadas que os tornam de confiança.
+
+**P:** O que vem depois dos harnesses?
+**R:** Provavelmente padronização e maturidade de ferramentaria — plataformas de harness compartilhadas, normas interoperáveis de observabilidade e avaliação, e governança integrada nos runtimes — mais do que um paradigma inteiramente novo. A unidade de responsabilidade (o sistema) já é estável.

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

@@ -0,0 +1,105 @@
+---
+title: "La taxonomía del harness"
+summary: "Descomposición precisa de los componentes del harness —memoria, herramientas, planificación, orquestación, observabilidad, evaluación, gobernanza y seguridad— y de cómo encajan entre sí."
+---
+
+# La taxonomía del harness
+
+## Resumen ejecutivo
+El harness no es un monolito: es un conjunto de componentes distintos, cada uno con una responsabilidad clara e interfaces claras con los demás. Este capítulo ofrece la taxonomía canónica: ocho componentes —memoria, herramientas, planificación, orquestación, observabilidad, evaluación, gobernanza y seguridad— organizados en tres capas (el bucle de ejecución, las preocupaciones transversales y los controles). La taxonomía es el mapa que el resto del manual rellena.
+
+## Conceptos clave
+- **Componente:** una parte acotada del harness con una única responsabilidad principal.
+- **Capa de ejecución:** los componentes que mueven el bucle percibir–razonar–actuar (planificación, orquestación, memoria, herramientas).
+- **Capa transversal:** preocupaciones que instrumentan o miden el bucle sin estar dentro de él (observabilidad, evaluación).
+- **Capa de control:** preocupaciones que limitan lo que el bucle puede hacer (gobernanza, seguridad).
+- **Interfaz:** el contrato por el que dos componentes intercambian información o autoridad.
+
+## Definición
+La **taxonomía del harness** es la descomposición canónica del andamiaje de ingeniería de un sistema agéntico en componentes y capas con nombre, definiendo la responsabilidad de cada componente y sus relaciones con los demás. Sirve como vocabulario compartido y como lista de verificación: un harness de calidad productiva debe abordar conscientemente cada componente, aunque elija una implementación mínima.
+
+## Explicación detallada
+
+La taxonomía organiza ocho componentes en tres capas. La estratificación importa: te dice qué componentes *hacen el trabajo*, cuáles *observan el trabajo* y cuáles *acotan el trabajo*.
+
+### Capa de ejecución — mueve el bucle
+Los componentes que producen realmente el comportamiento del agente.
+
+- **Planificación y gestión de objetivos (HRN-009):** descompone un objetivo en subobjetivos, decide la siguiente acción, gestiona la replanificación cuando un paso falla y detecta la finalización o el bloqueo. Responde a «¿qué debería pasar ahora?».
+- **Orquestación (HRN-010):** el runtime que ejecuta el bucle: ensambla el contexto, llama al modelo, despacha llamadas a herramientas, gestiona reintentos y tiempos de espera, enruta entre modelos o subagentes y aplica presupuestos. Responde a «quién se ejecuta, con qué, y qué ocurre con la salida».
+- **Memoria (HRN-005):** gobierna qué entra en el contexto del modelo: memoria de trabajo a corto plazo, almacenes de largo plazo, recuperación, compresión y olvido. Responde a «qué ve y qué recuerda el modelo».
+- **Herramientas / actuación:** los contratos tipados con los que el agente lee y escribe en los sistemas de la empresa, con validación explícita de entradas, esquemas de salida, idempotencia y semántica de fallo. Responde a «cómo afecta el agente al mundo».
+
+El modelo se sitúa *dentro* de esta capa como componente invocado, no como el sistema. Es el replanteamiento central de HRN-001.
+
+### Capa transversal — mide el bucle
+No producen comportamiento; hacen que el comportamiento sea visible y cuantificable.
+
+- **Observabilidad (HRN-006):** trazado, spans, registro estructurado, contabilidad de tokens y coste, y reproducción. Convierte una ejecución opaca y no determinista en un artefacto inspeccionable. Responde a «qué ocurrió, exactamente».
+- **Evaluación (HRN-007):** medición offline y online de la calidad: conjuntos dorados, LLM como juez, suites de regresión, métricas de finalización de tarea. Responde a «¿es realmente bueno, y va a mejor o a peor?».
+
+Observabilidad y evaluación son codependientes: la evaluación necesita las trazas que produce la observabilidad, y la observabilidad rinde más cuando sus datos alimentan la evaluación.
+
+### Capa de control — acota el bucle
+Limitan la autoridad y defienden el sistema.
+
+- **Gobernanza (HRN-008):** codifica política, flujos de aprobación, rendición de cuentas y auditabilidad como controles aplicados: puertas con humano en el bucle, políticas de acciones permitidas y registros de quién o qué autorizó cada acción. Responde a «¿está permitido, y quién responde?».
+- **Seguridad (HRN-011):** trata al modelo y a sus entradas como no confiables: defensa frente a inyección de prompts, aislamiento de herramientas, credenciales de mínimo privilegio, validación de salidas y controles de exfiltración de datos. Responde a «¿puede un adversario hacer que este sistema haga algo que no debe?».
+
+### Cómo componen los componentes
+Una petición entra por **planificación**, que entrega un plan a **orquestación**. La orquestación ensambla el contexto desde **memoria**, llama al **modelo** y enruta las acciones elegidas hacia **herramientas**. Durante todo el proceso, **observabilidad** registra cada span y **evaluación** puntúa resultados; **gobernanza** cierra el paso a las acciones de riesgo y **seguridad** vigila las fronteras. Las interfaces entre componentes son donde se gana o se pierde la fiabilidad: un contrato descuidado entre memoria y orquestación, o una llamada del modelo a una herramienta sin validar, son una fuente clásica de fallo en producción.
+
+### Cómo usar la taxonomía
+La taxonomía es también una **lista de madurez**. Para cada componente, pregunta: ¿lo tenemos, es explícito, está probado? Muchos proyectos de «agentes» implementan solo la capa de ejecución y salen a producción sin observabilidad, evaluación, gobernanza ni seguridad: los cuatro componentes que distinguen un sistema de una demo. Un harness equilibrado invierte en las tres capas.
+
+| Capa | Componente | Responsabilidad principal | Capítulo |
+|------|------------|---------------------------|----------|
+| Ejecución | Planificación y objetivos | Decidir la siguiente acción; replanificar | HRN-009 |
+| Ejecución | Orquestación | Ejecutar el bucle; enrutar; presupuestar | HRN-010 |
+| Ejecución | Memoria | Controlar el contexto; recuperar; olvidar | HRN-005 |
+| Ejecución | Herramientas / actuación | Actuar sobre el mundo mediante contratos | HRN-003 |
+| Transversal | Observabilidad | Trazar, registrar, contabilizar, reproducir | HRN-006 |
+| Transversal | Evaluación | Medir calidad; frenar regresiones | HRN-007 |
+| Control | Gobernanza | Aplicar política; aprobaciones; auditoría | HRN-008 |
+| Control | Seguridad | Defender frente a adversarios | HRN-011 |
+
+## Modos de fallo observados
+- **Capas ausentes:** implementar solo la capa de ejecución (un bucle que funciona) y omitir observabilidad, evaluación, gobernanza y seguridad: el precipicio de la demo a producción.
+- **Acoplamiento de componentes:** difuminar responsabilidades (por ejemplo, que la orquestación comprima memoria en silencio) de modo que los fallos no puedan aislarse ni probarse.
+- **Interfaces débiles:** contratos sin validar ni tipar entre componentes, en especial modelo→herramienta y recuperación→contexto, que propagan datos malos por todo el bucle.
+- **Exceso de orquestación:** construir topologías multiagente elaboradas antes de que los componentes de un solo agente sean fiables por separado.
+
+## KPIs
+| Métrica | Objetivo | Notas |
+|---------|----------|-------|
+| Cobertura de componentes | 8/8 abordados | Cada componente implementado conscientemente o dejado en mínimo de forma deliberada |
+| Tasa de validación de interfaces | 100 % de las llamadas modelo→herramienta | Evita propagar argumentos malformados o alucinados |
+| Tasa de finalización de tarea | Depende del dominio | Medida por evaluación (HRN-007) |
+
+## Métricas de coste
+El coste se concentra en la capa de ejecución (inferencia y llamadas a herramientas) y en el almacenamiento de observabilidad (el volumen de trazas escala con los pasos). La evaluación añade coste periódico por lotes. Gobernanza y seguridad son sobre todo coste fijo de ingeniería. Una heurística útil de presupuesto es atribuir el coste *por componente*, para que la optimización apunte al motor real del gasto y no al más visible.
+
+## Características de escalado
+Cada componente escala por un eje distinto: la orquestación con la concurrencia, la memoria con el estado retenido y el tamaño del corpus, la observabilidad con los pasos por ejecución, y la evaluación con el tamaño del corpus y las llamadas al juez. Como escalan de forma independiente, la taxonomía es también una herramienta de planificación de capacidad: los cuellos de botella aparecen en componentes concretos, no en «el agente» en abstracto.
+
+## Contenido relacionado
+- HRN-001 — Ingeniería de Harness: definición y panorama
+- HRN-005 — Memoria en sistemas agénticos
+- HRN-006 — Observabilidad para sistemas agénticos
+- HRN-009 — Planificación y gestión de objetivos
+- HRN-010 — Orquestación
+
+## Referencias
+- Literatura de práctica sobre arquitecturas de agentes y descomposición en componentes.
+- Observación de industria sobre la estructura de sistemas agénticos en producción, 2023–2026.
+- Santa María, S. — Notas de trabajo sobre la taxonomía del harness.
+
+## Preguntas frecuentes
+**P:** ¿Por qué ocho componentes y no más o menos?
+**R:** Ocho es el conjunto mínimo que cubre ejecutar el bucle, medirlo y acotarlo sin solaparse. Puedes subdividir (por ejemplo, separar herramientas de actuación), pero las responsabilidades siguen siendo las mismas.
+
+**P:** ¿El modelo es un componente del harness?
+**R:** El modelo es *invocado por* el harness y se sitúa dentro de la capa de ejecución, pero no forma parte del harness: el harness es precisamente todo lo que lo rodea.
+
+**P:** ¿Puede un sistema pequeño saltarse la capa de control?
+**R:** Para un juguete, sí; para un sistema empresarial, no. Gobernanza y seguridad son lo que hace seguro poner el sistema delante de clientes, reguladores y adversarios. Pueden ser mínimas, pero deben ser conscientes.

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

@@ -0,0 +1,158 @@
+---
+id: HRN-003
+title: The Harness Taxonomy
+domain: Harness
+category: Foundations
+status: Draft
+author: Santiago Santa María
+created: 2026-06-21
+updated: 2026-06-21
+summary: A structured taxonomy of the harness — memory, tools, planning, orchestration, observability, evaluation, governance, and security — naming each component, its responsibility, and how the parts compose into a reliable agentic system.
+evidence_level: theoretical
+confidence_level: medium
+source_type:
+  - industry_observation
+  - personal_experience
+related:
+  - HRN-001
+  - HRN-005
+  - HRN-006
+  - HRN-009
+  - HRN-010
+tags:
+  - taxonomy
+  - harness-engineering
+  - foundations
+  - architecture
+  - agentic-systems
+---
+
+# The Harness Taxonomy
+
+## Executive Summary
+The harness is not a monolith; it is a set of distinct components, each with a clear responsibility and clear interfaces to the others. This chapter provides the canonical taxonomy: eight components — memory, tools, planning, orchestration, observability, evaluation, governance, and security — organized into three layers (the execution loop, the cross-cutting concerns, and the controls). The taxonomy is the map the rest of the handbook fills in.
+
+## Key Concepts
+- **Component:** A bounded part of the harness with a single primary responsibility.
+- **Execution layer:** Components that drive the perceive–reason–act loop (planning, orchestration, memory, tools).
+- **Cross-cutting layer:** Concerns that instrument or measure the loop without being inside it (observability, evaluation).
+- **Control layer:** Concerns that constrain what the loop is allowed to do (governance, security).
+- **Interface:** The contract by which two components exchange information or authority.
+
+## Definition
+The **Harness Taxonomy** is the canonical decomposition of an agentic system's engineered scaffolding into named components and layers, defining each component's responsibility and its relationships to the others. It serves as a shared vocabulary and as a checklist: a production-grade harness must consciously address every component, even if it chooses a minimal implementation.
+
+## Architecture Diagram
+```mermaid
+flowchart TB
+  subgraph CONTROL["Control Layer — constrains the loop"]
+    GOV[Governance]
+    SEC[Security]
+  end
+  subgraph CROSS["Cross-cutting Layer — measures the loop"]
+    OBS[Observability]
+    EVAL[Evaluation]
+  end
+  subgraph EXEC["Execution Layer — runs the loop"]
+    PLAN[Planning & Goal Mgmt]
+    ORCH[Orchestration]
+    MEM[Memory]
+    TOOL[Tools / Actuation]
+    MODEL{{Model}}
+  end
+  PLAN --> ORCH
+  ORCH <--> MODEL
+  ORCH <--> MEM
+  ORCH <--> TOOL
+  OBS -. traces .-> EXEC
+  EVAL -. scores .-> EXEC
+  GOV -. policy gates .-> ORCH
+  SEC -. guards .-> TOOL
+  SEC -. sanitizes .-> MEM
+```
+
+## Detailed Explanation
+
+The taxonomy organizes eight components into three layers. The layering matters: it tells you which components *do work*, which ones *watch the work*, and which ones *bound the work*.
+
+### Execution Layer — runs the loop
+The components that actually produce the agent's behavior.
+
+- **Planning & Goal Management (HRN-009):** Decomposes a goal into sub-goals, decides the next action, manages re-planning when steps fail, and detects completion or impasse. Owns the question "what should happen next?"
+- **Orchestration (HRN-010):** The runtime that executes the loop — assembling context, calling the model, dispatching tool calls, handling retries and timeouts, routing between models or sub-agents, and enforcing budgets. Owns "who runs, with what, and what happens to the output."
+- **Memory (HRN-005):** Governs what enters the model's context: short-term working memory, long-term stores, retrieval, compression, and forgetting. Owns "what the model sees and remembers."
+- **Tools / Actuation:** The typed contracts through which the agent reads from and writes to enterprise systems, with explicit input validation, output schemas, idempotency, and failure semantics. Owns "how the agent affects the world."
+
+The model sits *inside* this layer as a called component, not as the system. This is the central reframing of HRN-001.
+
+### Cross-cutting Layer — measures the loop
+These do not produce behavior; they make behavior visible and quantifiable.
+
+- **Observability (HRN-006):** Tracing, spans, structured logging, token/cost accounting, and replay. Turns an opaque non-deterministic run into an inspectable artifact. Owns "what happened, exactly?"
+- **Evaluation (HRN-007):** Offline and online measurement of quality — golden sets, LLM-as-judge, regression suites, task-completion metrics. Owns "is it actually good, and is it getting better or worse?"
+
+Observability and evaluation are co-dependent: evaluation needs the traces observability produces, and observability is most valuable when its data feeds evaluation.
+
+### Control Layer — bounds the loop
+These constrain authority and defend the system.
+
+- **Governance (HRN-008):** Encodes policy, approval workflows, accountability, and auditability as enforced controls — human-in-the-loop gates, allowed-action policies, and records of who/what authorized each action. Owns "is this permitted, and who is accountable?"
+- **Security (HRN-011):** Treats the model and its inputs as untrusted: prompt-injection defense, tool sandboxing, least-privilege credentials, output validation, and data-exfiltration controls. Owns "can an adversary make this system do something it shouldn't?"
+
+### How the components compose
+A request enters through **planning**, which hands a plan to **orchestration**. Orchestration assembles context from **memory**, calls the **model**, and routes the model's chosen actions to **tools**. Throughout, **observability** records every span and **evaluation** scores outcomes; **governance** gates risky actions and **security** guards the boundaries. The interfaces between components are where reliability is won or lost — a sloppy memory-to-orchestration contract or an unvalidated model-to-tool call is a classic source of production failure.
+
+### Using the taxonomy
+The taxonomy is also a **maturity checklist**. For each component, ask: do we have it, is it explicit, and is it tested? Many "agent" projects implement only the execution layer and ship without observability, evaluation, governance, or security — the four components that distinguish a system from a demo. A balanced harness invests across all three layers.
+
+| Layer | Component | Primary responsibility | Chapter |
+|-------|-----------|------------------------|---------|
+| Execution | Planning & Goal Mgmt | Decide next action; re-plan | HRN-009 |
+| Execution | Orchestration | Run the loop; route; budget | HRN-010 |
+| Execution | Memory | Control context; retrieve; forget | HRN-005 |
+| Execution | Tools / Actuation | Act on the world via contracts | HRN-003 |
+| Cross-cutting | Observability | Trace, log, account, replay | HRN-006 |
+| Cross-cutting | Evaluation | Measure quality; guard regressions | HRN-007 |
+| Control | Governance | Enforce policy; approvals; audit | HRN-008 |
+| Control | Security | Defend against adversaries | HRN-011 |
+
+## Observed Failure Modes
+- **Missing layers:** Implementing only the execution layer (a working loop) and omitting observability, evaluation, governance, and security — the demo-to-production cliff.
+- **Component coupling:** Blurring responsibilities (e.g., orchestration silently doing memory compression) so failures cannot be isolated or tested.
+- **Weak interfaces:** Unvalidated, untyped contracts between components, especially model→tool and retrieval→context, which propagate bad data through the loop.
+- **Over-orchestration:** Building elaborate multi-agent topologies before the single-agent components are individually reliable.
+
+## KPIs
+| Metric | Target | Notes |
+|--------|--------|-------|
+| Component coverage | 8/8 addressed | Each taxonomy component consciously implemented or deliberately stubbed |
+| Interface validation rate | 100% of model→tool calls validated | Prevents propagation of malformed/hallucinated arguments |
+| Task completion rate | Domain-dependent | Measured by evaluation (HRN-007) |
+
+## Cost Metrics
+Cost concentrates in the execution layer (inference and tool calls) and in observability storage (trace volume scales with steps). Evaluation adds periodic batch cost. Governance and security are mostly fixed engineering cost. A useful budgeting heuristic is to attribute cost per *component* so optimization targets the real driver rather than the most visible one.
+
+## Scaling Characteristics
+Different components scale along different axes: orchestration scales with concurrency, memory with retained state and corpus size, observability with steps-per-run, and evaluation with corpus size and judge calls. Because the components scale independently, the taxonomy is also a capacity-planning tool — bottlenecks appear in specific components, not in "the agent" generically.
+
+## Related Content
+- HRN-001 — Harness Engineering: Definition and Overview
+- HRN-005 — Memory in Agentic Systems
+- HRN-006 — Observability for Agentic Systems
+- HRN-009 — Planning and Goal Management
+- HRN-010 — Orchestration
+
+## References
+- Practitioner literature on agent architectures and component decomposition.
+- Industry observation on production agent system structure, 2023–2026.
+- Santa María, S. — Working notes on the harness taxonomy.
+
+## FAQs
+**Q:** Why eight components and not more or fewer?
+**A:** Eight is the minimal set that covers running the loop, measuring it, and bounding it without overlap. You can sub-divide (e.g., split tools from actuation) but the responsibilities remain.
+
+**Q:** Is the model a component of the harness?
+**A:** The model is *called by* the harness and sits inside the execution layer, but it is not itself part of the harness — the harness is precisely everything around it.
+
+**Q:** Can a small system skip the control layer?
+**A:** For a toy, yes; for an enterprise system, no. Governance and security are what make the system safe to put in front of customers, regulators, and adversaries. They can be minimal but must be conscious.