santismm-knowledge-mcp 0.2.1

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

@@ -0,0 +1,105 @@
+---
+title: "Governança dentro do harness"
+summary: "Traduzir a política em controles aplicados: aprovações humanas, rastreabilidade, identidade do agente e prestação de contas exigíveis num ambiente regulado."
+---
+
+# Governança dentro do harness
+
+## Resumo executivo
+
+A governança não é um documento que vive numa wiki: num sistema agêntico confiável é uma **camada de execução do harness**. Este capítulo sustenta que as obrigações de IA empresarial (regulatórias, contratuais e baseadas em risco) têm de ser compiladas em controles executáveis situados no caminho crítico entre a intenção do modelo e a ação do sistema. A Engenharia de Harness trata a governança como código: pontos de decisão de política, portas de aprovação e guarda-corpos que observam, permitem, transformam ou bloqueiam cada chamada a ferramenta. Sem essa camada, a autonomia de um agente está por governar por construção; com ela, a autonomia se torna limitada, auditável e defensável.
+
+## Conceitos-chave
+
+- **Ponto de aplicação de política (PEP):** o componente do harness que intercepta uma ação do agente e consulta uma decisão.
+- **Ponto de decisão de política (PDP):** o motor que avalia a política contra o contexto da ação e devolve permitir, negar ou transformar.
+- **Guarda-corpo:** uma verificação em execução sobre entradas ou saídas (conteúdo, esquema, dados pessoais, jurisdição) que restringe o comportamento.
+- **Porta de aprovação:** um controle que suspende a execução à espera de uma decisão humana ou de uma autoridade superior (ver PAT-001).
+- **Política como código:** regras de governança expressas num formato declarativo, versionado e testável.
+- **Rastro de auditoria:** o registro imutável do que foi tentado, do que foi decidido e por quê.
+
+## Definição
+
+> A **governança dentro do harness** é a disciplina de incorporar a aplicação de políticas, os fluxos de aprovação e os guarda-corpos como uma camada de execução de primeira classe de um sistema agêntico, de modo que toda a ação iniciada pelo modelo seja mediada por uma decisão explícita e auditável derivada da política da empresa.
+
+## Explicação detalhada
+
+A camada de governança se estrutura em torno da clássica **separação PEP/PDP** tomada da arquitetura de autorização (XACML, OPA) e adaptada a agentes não deterministas. O ponto de aplicação é tecido no caminho de invocação de ferramentas do harness, de modo que *nenhuma* ação com efeito — enviar um email, escrever numa base de dados, transferir fundos, chamar uma API externa — chegue a um efetor sem ser avaliada antes. O ponto de decisão avalia a ação contra um **pacote de políticas**: um conjunto de regras versionado e testável que cobre em nome de quem o agente age, que classes de dados toca, que jurisdições se aplicam e que limites de despesa ou de raio de impacto estão em vigor.
+
+Para além do simples permitir/negar importam três resultados de aplicação. **Transformar** permite ao harness autorizar uma ação neutralizando seu risco: redigir dados pessoais antes de uma chamada de saída, reduzir o âmbito de uma consulta ou limitar o montante de uma transação. **Escalar** encaminha a ação para uma porta de aprovação (PAT-001), suspendendo de forma duradoura o plano do agente até que um humano ou um agente supervisor decida. **Negar com explicação** devolve uma justificação estruturada ao contexto do agente para que o ciclo de raciocínio replaneie em vez de repetir às cegas.
+
+Os guarda-corpos operam em duas fronteiras. Os *guarda-corpos de entrada* filtram o conteúdo recuperado e as instruções do usuário à procura de injeção, padrões de jailbreak e pedidos fora de âmbito antes de influenciarem o plano. Os *guarda-corpos de saída* validam o conteúdo gerado e os argumentos estruturados das ferramentas contra esquema, política de conteúdo e regras de fuga de dados antes de atravessarem a fronteira de confiança. E algo essencial: os guarda-corpos são **em camadas, não únicos**. Um só classificador é um único ponto de falha, portanto a defesa em profundidade combina verificações deterministas (expressões regulares, esquema, listas de permitidos), estatísticas (classificadores) e baseadas em modelo (LLM como juiz), com valores padrão conservadores de fechamento em caso de falha para as ações de alto risco.
+
+A governança define ainda o **gradiente de autonomia**. O harness atribui a cada classe de ação um modo de controle dentro de um espectro: totalmente autônomo, autônomo com registro, humano no ciclo (aprovação obrigatória) ou humano sobre o ciclo (o humano pode interromper). Esse mapeamento é ele próprio política: um reembolso abaixo de 50 € pode ser autônomo; um reembolso acima de 5.000 €, ou qualquer ação que toque dados regulados, exige uma porta de aprovação. A taxonomia destes modos de controle se liga diretamente à taxonomia do harness (HRN-003) e ao quadro de governança empresarial (GOV-001), que fornece as obrigações que esta camada compila.
+
+Por fim, a governança só é credível se for **observável e demonstrável**. Cada decisão — a ação proposta, a versão de política consultada, as entradas, o veredicto e a justificação — é escrita num rastro de auditoria imutável e consultável. É isso que converte “temos uma política de IA” em “podemos demonstrar, ação a ação, que a política foi aplicada”, que é o patamar probatório que reguladores e auditores aplicam de fato.
+
+## Evidência de produção
+
+> **Cenário ilustrativo e representativo.** Nível de evidência: teórico · Confiança: média · Fonte: observação de indústria, experiência pessoal. Os números seguintes são intervalos realistas extraídos de padrões observados, não medições de uma implantação verificada concreta.
+
+- **Contexto:** um agente de back-office de serviços financeiros que redige e executa remediações a clientes.
+- **Cenário:** o agente deve resolver autonomamente disputas de valor baixo sem nunca movimentar fundos acima de um limiar nem tocar dados de outro cliente.
+- **Tecnologia:** orquestrador com um PEP em cada chamada a ferramenta; pacote de políticas ao estilo OPA; guarda-corpos de classificador, esquema e lista de permitidos; fila de aprovação duradoura.
+- **Carga:** dezenas de milhares de ações por dia, com uma percentagem de um só dígito encaminhada para portas de aprovação.
+- **Resultados (representativos):** em implantações ilustrativas desta forma, as camadas de governança costumam reduzir numa ordem de grandeza as violações de política de severidade alta diante de uma linha de base por governar, à custa de uma latência acrescentada por ação da ordem das dezenas baixas de milissegundos para as verificações deterministas, e de uma latência ponta a ponta nas ações escaladas limitada pelo tempo de resposta humano.
+
+### Lições aprendidas
+
+Os valores padrão de fechamento em caso de falha nas classes de ação de alto risco não são negociáveis; as falhas caras vêm de ações que *nunca foram avaliadas* porque se acrescentou uma ferramenta nova sem a política correspondente. A governança tem, por isso, de controlar o **registro de ferramentas**, não apenas sua invocação.
+
+## Modos de falha observados
+
+| Modo de falha | Gatilho | Mitigação |
+|---|---|---|
+| Contorno de política | Ferramenta nova acrescentada sem gancho PEP | Controlar o registro de ferramentas; negar por padrão o que não está mapeado |
+| Evasão de guarda-corpo | A injeção de prompt reescreve a intenção e passa um único classificador | Guarda-corpos em camadas com fechamento em caso de falha; verificações de entrada e de saída |
+| Fadiga de aprovação | Portas demasiado largas inundam os humanos, que carimbam sem olhar | Portas por nível de risco; auto-aprovar o de baixo risco com registro |
+| Política desatualizada | O pacote de políticas se desalinha da regulação | Versionar e testar a política como código; revisão periódica de conformidade |
+| Transformação silenciosa | A redação corrompe uma ação legítima | Registar as transformações; devolver a justificação ao contexto do agente |
+| Lacunas de auditoria | As decisões não são persistidas antes de a ação ser executada | Auditoria por escrita antecipada; negar se o destino de auditoria não estiver disponível |
+
+## KPIs
+
+| Métrica | Objetivo | Notas |
+|---|---|---|
+| Cobertura de política (classes de ação mapeadas) | 100 % | Por mapear → negar por padrão |
+| Taxa de violações de severidade alta | → 0 | Por cada 10.000 ações |
+| Precisão da porta de aprovação | Alta | Fração de escalonamentos que se justificavam |
+| Latência de decisão (p95) | < 50 ms no determinista | Exclui a espera de aprovação humana |
+| Completude de auditoria | 100 % | Toda a ação com efeito tem registro de decisão |
+| Tempo médio de atualização de política | Baixo (horas) | CI/CD de política como código |
+
+## Métricas de custo
+
+- **Sobrecusto de governança por ação:** as verificações deterministas acrescentam computação desprezável; os guarda-corpos baseados em modelo acrescentam uma ou mais chamadas de inferência auxiliares, que devem ser orçamentadas dentro do custo por tarefa.
+- **Custo de aprovação humana:** o custo variável dominante; minimiza-se com uma classificação de risco precisa para que só escale o que o merece.
+- **Custo de engenharia:** redação de políticas e testes de conformidade; amortiza-se reutilizando pacotes de políticas entre agentes.
+
+## Características de escalabilidade
+
+A aplicação determinista escala horizontalmente e sem estado junto do orquestrador. Os guarda-corpos baseados em modelo escalam com a capacidade de inferência e são o gargalo de débito com volumes altos de ações: coloque-os em cache e faça curto-circuito antes com verificações deterministas baratas. As portas de aprovação escalam com capacidade humana, não com computação, portanto o objetivo de desenho é manter a fração escalada pequena e estável à medida que o volume de ações cresce.
+
+## Conteúdo relacionado
+
+- HRN-003 — Taxonomia de camadas do harness e modos de controle.
+- GOV-001 — Quadro de governança de IA empresarial (as obrigações que esta camada aplica).
+- PAT-001 — Padrão de aprovação humana (o mecanismo da porta de aprovação).
+
+## Referências
+
+- NIST AI Risk Management Framework (AI RMF 1.0).
+- ISO/IEC 42001:2023 — sistemas de gestão de IA.
+- OASIS XACML e o modelo de autorização PEP/PDP.
+- Open Policy Agent (OPA) — motor de política como código.
+
+## Perguntas frequentes
+
+**P: Porque não resolver a governança no prompt?**
+R: As instruções do prompt são orientadoras e derrubáveis por injeção; a aplicação ao nível do harness é obrigatória e auditável. A governança tem de ficar fora da superfície persuadível do modelo.
+
+**P: Controlar cada ação não acrescenta demasiada latência?**
+R: As verificações deterministas custam entre uns poucos e umas dezenas de milissegundos. Só as ações escaladas incorrem em demora à escala humana, e são deliberadamente raras.
+
+**P: Em que difere isto de GOV-001?**
+R: GOV-001 define as obrigações e o quadro; HRN-008 é como essas obrigações são compiladas em controles de execução dentro do harness.

package/content/harness/HRN-009-planning-and-goal-management.es.md

@@ -0,0 +1,102 @@
+---
+title: "Planificación y gestión de objetivos"
+summary: "Descomposición de objetivos, gestión de subobjetivos y replanificación: cuándo deja el harness decidir al modelo y cuándo fija el camino en código."
+---
+
+# Planificación y gestión de objetivos
+
+## Resumen ejecutivo
+
+Un agente fiable no se limita a reaccionar token a token: persigue un objetivo a través de un plan representado e inspeccionable. La planificación y gestión de objetivos es la capa del harness que convierte un objetivo de alto nivel en un plan estructurado y ejecutable, sigue su estado a lo largo de una ejecución de horizonte largo y lo revisa cuando la realidad se aparta de lo previsto. Este capítulo trata el plan como una **estructura de datos de primera clase** propiedad del harness, no como una cadena de pensamiento efímera atrapada en la ventana de contexto. Externalizar el plan es lo que hace el comportamiento del agente auditable, reanudable y recuperable.
+
+## Conceptos clave
+
+- **Objetivo:** el estado final deseado que se encarga al agente, con criterios de éxito.
+- **Plan:** un conjunto ordenado o parcialmente ordenado de tareas que se espera que alcancen el objetivo.
+- **Tarea o paso:** una unidad atómica de trabajo mapeada a una o varias llamadas a herramienta.
+- **Descomposición:** el acto de partir un objetivo en tareas (véase PAT-010).
+- **Representación del plan:** la estructura explícita (lista, árbol, DAG, máquina de estados) en la que se almacena el plan.
+- **Replanificación:** revisar el plan en respuesta a un fallo, a información nueva o a un cambio de restricciones.
+- **Estado del plan:** el registro duradero de qué pasos están pendientes, en curso, hechos o fallidos.
+
+## Definición
+
+> La **planificación y gestión de objetivos** es la disciplina del harness que representa un objetivo y su plan descompuesto como estado explícito y duradero; selecciona y secuencia tareas contra ese plan; y reconcilia continuamente el plan con los resultados observados mediante replanificación.
+
+## Explicación detallada
+
+La planificación empieza por la **descomposición**: convertir un objetivo en tareas cuya finalización, en conjunto, satisface los criterios de éxito del objetivo (PAT-010 nombra este patrón). Las estrategias de descomposición intercambian coste por adaptabilidad. *Planificar y luego ejecutar* fija un plan completo por adelantado: barato, predecible y fácil de gobernar, pero frágil cuando el mundo lo sorprende. La *planificación entrelazada* (la familia ReAct) planifica un paso cada vez a partir de las observaciones: adaptable y robusta, pero más cara y más difícil de acotar. La *planificación jerárquica* combina ambas: un plan grueso de fases, cada una expandida en pasos concretos justo a tiempo. Los harness maduros eligen según la tarea: los flujos deterministas y bien entendidos favorecen planificar y luego ejecutar; la investigación abierta favorece el entrelazado.
+
+La **representación del plan** es la decisión portante. Una lista plana de tareas basta para trabajo lineal; un **DAG** captura dependencias y desbloquea el paralelismo (el orquestador, HRN-010, puede despachar ramas independientes de forma concurrente); una **máquina de estados** es lo adecuado cuando las transiciones están gobernadas y deben poder enumerarse de forma exhaustiva. Sea cual sea la forma, el plan debe estar *externalizado y persistido*. Un plan que solo vive dentro del contexto del modelo se pierde ante una caída, es invisible para la observabilidad e imposible de gobernar. Externalizarlo permite al harness reanudar desde el último estado duradero, permite a las personas inspeccionarlo y editarlo, y permite a la capa de gobernanza (HRN-008) razonar sobre lo que el agente pretende hacer *antes* de que lo haga.
+
+La **gestión de objetivos** es la capa por encima de los planes concretos. Sigue los criterios de éxito de forma explícita, de modo que la finalización se *verifica* en lugar de que la afirme el modelo. Gestiona subobjetivos y sus dependencias, resuelve conflictos y prioridades entre objetivos, y hace cumplir condiciones de terminación —presupuestos de pasos, de tiempo y techos de coste— que evitan el fallo clásico de un agente iterando eternamente sobre un objetivo inalcanzable. Los criterios de terminación forman parte de la especificación del objetivo, no son una ocurrencia tardía.
+
+La **replanificación** es donde la planificación se gana su sitio en un sistema *fiable*. El mundo no es estacionario: las herramientas fallan, los datos caducan, las suposiciones se rompen. El bucle de replanificación compara el resultado de cada paso con lo esperado y dispara una revisión ante la divergencia: un paso fallido, una precondición que ya no se cumple o información nueva que invalida las tareas posteriores. Una replanificación eficaz es *acotada*: prefiere la reparación local (reintentar, sustituir una herramienta, insertar un paso de recuperación) a descartar el plan entero, y escala a una redescomposición completa solo cuando la reparación local falla repetidamente. Esto enlaza directamente con los patrones de estrategia de recuperación y evita que la replanificación entre en bucle. Un presupuesto de replanificación —un tope al número de veces que un plan puede revisarse antes de escalar a un humano o a un supervisor— impide que el agente queme coste dentro de un bucle de planificación.
+
+## Evidencia de producción
+
+> **Escenario ilustrativo y representativo.** Nivel de evidencia: teórico · Confianza: media · Fuente: observación de industria, experiencia personal. Los rangos siguientes son representativos de patrones observados, no mediciones de un sistema verificado concreto.
+
+- **Contexto:** un agente de migración de datos de varios pasos que reconcilia registros entre sistemas.
+- **Escenario:** el objetivo («migrar y reconciliar la cuenta X») se descompone en fases de extracción, transformación, validación y carga, con dependencias entre pasos.
+- **Tecnología:** plan en DAG persistido en un almacén duradero; replanificación entrelazada ante fallos de validación; presupuestos de pasos y de coste.
+- **Carga:** tareas de horizonte largo que abarcan de minutos a horas, con decenas de pasos cada una.
+- **Resultados (representativos):** externalizar el plan y añadir replanificación acotada suele elevar sustancialmente la tasa de finalización de tarea frente a una línea base de planificar una sola vez, en tareas con tasas de fallo realistas, sobre todo por recuperarse localmente de fallos transitorios en lugar de abortar la ejecución entera.
+
+### Lecciones aprendidas
+
+Las mayores ganancias de fiabilidad no vienen de planes iniciales más inteligentes, sino de una **replanificación barata y bien acotada** y de **presupuestos de terminación explícitos**. Los agentes sin límite fallan iterando; los agentes acotados fallan de forma segura y escalan.
+
+## Modos de fallo observados
+
+| Modo de fallo | Disparador | Mitigación |
+|---|---|---|
+| Pérdida del plan ante una caída | El plan solo vive en el contexto | Persistir el plan como estado duradero |
+| Bucle infinito | Sin presupuesto de terminación | Presupuestos de pasos, tiempo y coste, más tope de replanificación |
+| Sobredescomposición | El objetivo se parte en microtareas triviales | Ajustar la granularidad del paso a las llamadas a herramienta |
+| Replanificación en bucle | Redescomposición completa ante cada fallo menor | Reparación local acotada antes de replanificar globalmente |
+| Finalización sin verificar | El modelo afirma haber terminado sin comprobar los criterios | Verificación explícita de los criterios de éxito |
+| Violación de dependencias | Un paso se ejecuta antes de que su precondición se cumpla | Orden del DAG impuesto por el orquestador |
+
+## KPIs
+
+| Métrica | Objetivo | Notas |
+|---|---|---|
+| Tasa de finalización de tarea | Alta | A nivel de objetivo, con criterios verificados |
+| Pasos por tarea | Mínimos | Menos es más barato; vigilar la sobredescomposición |
+| Tasa de replanificación | Baja o moderada | Los picos señalan planes frágiles o herramientas inestables |
+| Éxito de recuperación del plan | Alto | Fracción de fallos reparados sin abortar |
+| Tasa de incumplimiento de presupuesto | → 0 | Tareas que topan con los techos de pasos o coste |
+
+## Métricas de coste
+
+- El **coste por tarea** escala con pasos × inferencia por paso + coste de herramientas; la sobredescomposición lo infla directamente.
+- **Sobrecoste de planificación:** la planificación entrelazada añade una llamada de inferencia por paso; planificar y luego ejecutar amortiza una única llamada de planificación entre muchos pasos.
+- **Coste de replanificación:** cada replanificación es inferencia adicional; el tope de replanificación acota el coste en el peor caso por tarea.
+
+## Características de escalado
+
+Los planes en DAG escalan el rendimiento de ejecución al exponer al orquestador las ramas paralelizables. La complejidad del plan escala el coste de inferencia de planificación de forma superlineal, así que la descomposición jerárquica (planificar fases a grandes rasgos y expandir de forma perezosa) mantiene acotado el coste de planificación por tarea a medida que crecen los objetivos. El estado duradero del plan escala con el número de objetivos concurrentes en vuelo, no con su longitud, lo que convierte al almacén de estado en el componente que hay que dimensionar para la concurrencia.
+
+## Contenido relacionado
+
+- HRN-003 — Dónde encaja la planificación en la taxonomía del harness.
+- HRN-010 — La orquestación ejecuta el plan y despacha las ramas paralelas.
+- PAT-010 — Patrón de descomposición de objetivos.
+
+## Referencias
+
+- Yao et al., «ReAct: Synergizing Reasoning and Acting in Language Models».
+- Wang et al., «Plan-and-Solve Prompting».
+- Planificación clásica en IA: literatura sobre STRIPS y HTN (redes jerárquicas de tareas).
+
+## Preguntas frecuentes
+
+**P: ¿Debe vivir el plan en la ventana de contexto?**
+R: No. Persístelo como estado duradero. El contexto es volátil, limitado en tamaño e ingobernable; un plan persistido es reanudable, inspeccionable y auditable.
+
+**P: ¿Planificar y luego ejecutar, o entrelazar?**
+R: Elige según la tarea. Los flujos deterministas favorecen planificar y luego ejecutar; las tareas abiertas o propensas a fallar favorecen la replanificación entrelazada. La planificación jerárquica mezcla ambas.
+
+**P: ¿Cómo evito que un agente itere para siempre?**
+R: Haz que los criterios de terminación formen parte del objetivo: presupuestos de pasos, tiempo y coste más un tope de replanificación, con escalado a un humano o supervisor al incumplirlos.

package/content/harness/HRN-009-planning-and-goal-management.md

@@ -0,0 +1,142 @@
+---
+id: HRN-009
+title: Planning and Goal Management
+domain: Harness
+category: Planning
+status: Draft
+author: Santiago Santa María
+created: 2026-06-21
+updated: 2026-06-21
+summary: Planning and goal management is the harness layer that decomposes goals into executable plans, represents and tracks plan state, and replans under failure, making agent autonomy directed rather than reactive.
+evidence_level: theoretical
+confidence_level: medium
+source_type:
+  - industry_observation
+  - personal_experience
+related:
+  - HRN-003
+  - HRN-010
+  - PAT-010
+tags:
+  - planning
+  - goal-decomposition
+  - replanning
+  - task-management
+  - plan-representation
+---
+
+# Planning and Goal Management
+
+## Executive Summary
+
+A reliable agent does not merely react token-by-token — it pursues a goal through a represented, inspectable plan. Planning and goal management is the harness layer that turns a high-level objective into a structured, executable plan, tracks its state across long-horizon execution, and revises it when reality diverges from expectation. This chapter treats the plan as a **first-class data structure** owned by the harness, not an ephemeral chain-of-thought trapped in the context window. Externalizing the plan is what makes agent behavior auditable, resumable, and recoverable.
+
+## Key Concepts
+
+- **Goal:** the desired end-state the agent is commissioned to achieve, with success criteria.
+- **Plan:** an ordered or partially-ordered set of tasks expected to achieve the goal.
+- **Task / step:** an atomic unit of work mapped to one or more tool calls.
+- **Decomposition:** the act of breaking a goal into tasks (see PAT-010).
+- **Plan representation:** the explicit structure (list, tree, DAG, state machine) the plan is stored in.
+- **Replanning:** revising the plan in response to failure, new information, or changed constraints.
+- **Plan state:** the durable record of which steps are pending, in-progress, done, or failed.
+
+## Definition
+
+> **Planning and goal management** is the harness discipline of representing a goal and its decomposed plan as explicit, durable state; selecting and sequencing tasks against that plan; and continuously reconciling the plan with observed outcomes through replanning.
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    GOAL[Goal + Success Criteria] --> DEC[Decomposition]
+    DEC --> PLAN[(Plan as DAG\npersisted state)]
+    PLAN --> SEL[Task Selector]
+    SEL --> EXE[Execute Step\nvia Orchestrator]
+    EXE --> OBS[Observe Outcome]
+    OBS -->|success| UPD[Update Plan State]
+    OBS -->|failure / new info| REP[Replan]
+    REP --> PLAN
+    UPD --> DONE{Goal\nsatisfied?}
+    DONE -->|no| SEL
+    DONE -->|yes| END[Report + Verify]
+    UPD --> PLAN
+```
+
+## Detailed Explanation
+
+Planning begins with **decomposition**: converting a goal into tasks whose completion, in aggregate, satisfies the goal's success criteria (PAT-010 names this pattern). Decomposition strategies trade off cost against adaptivity. *Plan-then-execute* commits a full plan up front — cheap, predictable, and easy to govern, but brittle when the world surprises it. *Interleaved planning* (the ReAct family) plans one step at a time from observations — adaptive and robust, but more expensive and harder to bound. *Hierarchical planning* combines them: a coarse plan of phases, each expanded just-in-time into concrete steps. Mature harnesses choose per-task: deterministic, well-understood workflows favor plan-then-execute; open-ended research favors interleaving.
+
+The **plan representation** is the load-bearing decision. A flat task list suffices for linear work; a **DAG** captures dependencies and unlocks parallelism (the orchestrator, HRN-010, can dispatch independent branches concurrently); a **state machine** is right when transitions are governed and must be exhaustively enumerable. Whatever the shape, the plan must be *externalized and persisted*. A plan living only inside the model's context is lost on a crash, invisible to observability, and impossible to govern. Externalizing it lets the harness resume from the last durable state, lets humans inspect and edit it, and lets the governance layer (HRN-008) reason about what the agent intends to do *before* it does it.
+
+**Goal management** is the layer above individual plans. It tracks success criteria explicitly, so completion is *verified* rather than asserted by the model. It manages sub-goals and their dependencies, handles goal conflicts and prioritization, and enforces termination conditions — step budgets, time budgets, and cost ceilings — that prevent the classic failure of an agent looping forever on an unachievable goal. Termination criteria are part of the goal specification, not an afterthought.
+
+**Replanning** is where planning earns its place in a *reliable* system. The world is non-stationary: tools fail, data is stale, assumptions break. The replanning loop watches each step's outcome against expectation and triggers revision on divergence — a failed step, a precondition that no longer holds, or new information that invalidates downstream tasks. Effective replanning is *scoped*: prefer local repair (retry, substitute a tool, insert a recovery step) over discarding the whole plan, and escalate to full re-decomposition only when local repair fails repeatedly. This connects directly to recovery strategy patterns and keeps replanning from thrashing. A replan budget — a cap on how many times a plan may be revised before escalating to a human or supervisor — prevents the agent from burning cost in a planning loop.
+
+## Production Evidence
+
+> **Illustrative / representative scenario.** Evidence level: theoretical · Confidence: medium · Source: industry_observation, personal_experience. Ranges below are representative of observed patterns, not measurements from one verified system.
+
+- **Context:** A multi-step data-migration agent reconciling records across systems.
+- **Scenario:** The goal ("migrate and reconcile account X") decomposes into extract, transform, validate, and load phases with inter-step dependencies.
+- **Technology:** DAG plan persisted to a durable store; interleaved replanning on validation failures; step + cost budgets.
+- **Load:** Long-horizon tasks spanning minutes to hours, dozens of steps each.
+- **Results (representative):** Externalizing the plan and adding scoped replanning typically lifts task-completion rate substantially over a plan-once baseline on tasks with realistic failure rates, primarily by recovering from transient failures locally instead of aborting the whole run.
+
+### Lessons Learned
+
+The biggest reliability gains come not from smarter initial plans but from **cheap, well-scoped replanning** and **explicit termination budgets**. Unbounded agents fail by looping; bounded agents fail safely and escalate.
+
+## Observed Failure Modes
+
+| Failure Mode | Trigger | Mitigation |
+|---|---|---|
+| Plan loss on crash | Plan held only in context | Persist plan as durable state |
+| Infinite loop | No termination budget | Step/time/cost budgets + replan cap |
+| Over-decomposition | Goal split into trivial micro-steps | Right-size step granularity to tool calls |
+| Replan thrash | Full re-decomposition on every minor failure | Scoped local repair before global replan |
+| Unverified completion | Model asserts done without checking criteria | Explicit success-criteria verification |
+| Dependency violation | Step run before its precondition holds | DAG ordering enforced by orchestrator |
+
+## KPIs
+
+| Metric | Target | Notes |
+|---|---|---|
+| Task completion rate | High | Goal-level, criteria-verified |
+| Steps per task | Minimal | Lower is cheaper; watch over-decomposition |
+| Replan rate | Low–moderate | Spikes signal brittle plans or flaky tools |
+| Plan recovery success | High | Fraction of failures repaired without abort |
+| Budget breach rate | → 0 | Tasks hitting step/cost ceilings |
+
+## Cost Metrics
+
+- **Cost per task** scales with steps × per-step inference + tool cost; over-decomposition inflates it directly.
+- **Planning overhead:** interleaved planning adds an inference call per step; plan-then-execute amortizes one planning call across many steps.
+- **Replan cost:** each replan is additional inference; the replan cap bounds worst-case cost per task.
+
+## Scaling Characteristics
+
+DAG plans scale execution throughput by exposing parallelizable branches to the orchestrator. Plan complexity scales the planning-inference cost super-linearly, so hierarchical decomposition (plan phases coarsely, expand lazily) keeps per-task planning cost bounded as goals grow. Durable plan state scales with the number of concurrent in-flight goals, not their length, making the state store the component to size for concurrency.
+
+## Related Content
+
+- HRN-003 — Where planning sits in the harness taxonomy.
+- HRN-010 — Orchestration executes the plan and dispatches parallel branches.
+- PAT-010 — Goal Decomposition pattern.
+
+## References
+
+- Yao et al., "ReAct: Synergizing Reasoning and Acting in Language Models."
+- Wang et al., "Plan-and-Solve Prompting."
+- Classical AI planning: STRIPS / HTN (hierarchical task network) planning literature.
+
+## FAQs
+
+**Q: Should the plan live in the context window?**
+A: No. Persist it as durable state. Context is volatile, size-limited, and ungovernable; a persisted plan is resumable, inspectable, and auditable.
+
+**Q: Plan-then-execute or interleaved?**
+A: Choose per task. Deterministic workflows favor plan-then-execute; open-ended or failure-prone tasks favor interleaved replanning. Hierarchical planning blends both.
+
+**Q: How do I stop an agent from looping forever?**
+A: Make termination criteria part of the goal: step, time, and cost budgets plus a replan cap, with escalation to a human or supervisor on breach.

package/content/harness/HRN-009-planning-and-goal-management.pt.md

@@ -0,0 +1,102 @@
+---
+title: "Planejamento e gestão de objetivos"
+summary: "Decomposição de objetivos, gestão de subobjetivos e replanejamento: quando o harness deixa o modelo decidir e quando fixa o caminho em código."
+---
+
+# Planejamento e gestão de objetivos
+
+## Resumo executivo
+
+Um agente confiável não se limita a reagir token a token: persegue um objetivo através de um plano representado e inspecionável. O planejamento e gestão de objetivos é a camada do harness que converte um objetivo de alto nível num plano estruturado e executável, acompanha seu estado ao longo de uma execução de horizonte longo e o revisa quando a realidade se afasta do previsto. Este capítulo trata o plano como uma **estrutura de dados de primeira classe** pertencente ao harness, não como uma cadeia de pensamento efêmera presa na janela de contexto. Externalizar o plano é o que torna o comportamento do agente auditável, retomável e recuperável.
+
+## Conceitos-chave
+
+- **Objetivo:** o estado final desejado que é atribuído ao agente, com critérios de sucesso.
+- **Plano:** um conjunto ordenado ou parcialmente ordenado de tarefas que se espera que alcancem o objetivo.
+- **Tarefa ou passo:** uma unidade atômica de trabalho mapeada para uma ou mais chamadas a ferramenta.
+- **Decomposição:** o ato de dividir um objetivo em tarefas (ver PAT-010).
+- **Representação do plano:** a estrutura explícita (lista, árvore, DAG, máquina de estados) em que o plano é armazenado.
+- **Replanejamento:** rever o plano em resposta a uma falha, a informação nova ou a uma mudança de restrições.
+- **Estado do plano:** o registro duradouro de que passos estão pendentes, em andamento, concluídos ou com falha.
+
+## Definição
+
+> O **planejamento e gestão de objetivos** é a disciplina do harness que representa um objetivo e seu plano decomposto como estado explícito e duradouro; seleciona e sequencia tarefas contra esse plano; e reconcilia continuamente o plano com os resultados observados através de replanejamento.
+
+## Explicação detalhada
+
+O planejamento começa pela **decomposição**: converter um objetivo em tarefas cuja conclusão, no conjunto, satisfaz os critérios de sucesso do objetivo (PAT-010 nomeia este padrão). As estratégias de decomposição trocam custo por adaptabilidade. *Planejar e depois executar* fixa um plano completo à partida: barato, previsível e fácil de governar, mas frágil quando o mundo o surpreende. O *planejamento entrelaçado* (a família ReAct) planeja um passo de cada vez a partir das observações: adaptável e robusto, mas mais caro e mais difícil de limitar. O *planejamento hierárquico* combina os dois: um plano grosseiro de fases, cada uma expandida em passos concretos mesmo a tempo. Os harnesses maduros escolhem consoante a tarefa: os fluxos deterministas e bem compreendidos favorecem planejar e depois executar; a investigação aberta favorece o entrelaçamento.
+
+A **representação do plano** é a decisão portante. Uma lista plana de tarefas basta para trabalho linear; um **DAG** captura dependências e desbloqueia o paralelismo (o orquestrador, HRN-010, pode despachar ramos independentes simultaneamente); uma **máquina de estados** é o adequado quando as transições são governadas e têm de poder ser enumeradas exaustivamente. Seja qual for a forma, o plano tem de estar *externalizado e persistido*. Um plano que só vive dentro do contexto do modelo se perde numa queda, é invisível para a observabilidade e impossível de governar. Externalizá-lo permite ao harness retomar a partir do último estado duradouro, permite às pessoas inspecioná-lo e editá-lo, e permite à camada de governança (HRN-008) raciocinar sobre o que o agente tenciona fazer *antes* de o fazer.
+
+A **gestão de objetivos** é a camada acima dos planos concretos. Acompanha os critérios de sucesso de forma explícita, de modo que a conclusão é *verificada* em vez de afirmada pelo modelo. Gerencia subobjetivos e suas dependências, resolve conflitos e prioridades entre objetivos, e faz cumprir condições de terminação — orçamentos de passos, de tempo e tetos de custo — que evitam a falha clássica de um agente iterando eternamente sobre um objetivo inalcançável. Os critérios de terminação fazem parte da especificação do objetivo, não são uma ideia posterior.
+
+O **replanejamento** é onde o planejamento ganha seu lugar num sistema *confiável*. O mundo não é estacionário: as ferramentas falham, os dados expiram, os pressupostos se quebram. O ciclo de replanejamento compara o resultado de cada passo com o esperado e desencadeia uma revisão perante a divergência: um passo com falha, uma pré-condição que não se verifica mais ou informação nova que invalida as tarefas seguintes. Um replanejamento eficaz é *limitado*: prefira a reparação local (repetir, substituir uma ferramenta, inserir um passo de recuperação) a descartar o plano inteiro, e escale para uma redecomposição completa apenas quando a reparação local falha repetidamente. Isto se liga diretamente aos padrões de estratégia de recuperação e evita que o replanejamento entre em ciclo. Um orçamento de replanejamento — um limite ao número de vezes que um plano pode ser revisto antes de escalar para um humano ou um supervisor — impede que o agente queime custo dentro de um ciclo de planejamento.
+
+## Evidência de produção
+
+> **Cenário ilustrativo e representativo.** Nível de evidência: teórico · Confiança: média · Fonte: observação de indústria, experiência pessoal. Os intervalos seguintes são representativos de padrões observados, não medições de um sistema verificado concreto.
+
+- **Contexto:** um agente de migração de dados de vários passos que reconcilia registros entre sistemas.
+- **Cenário:** o objetivo (“migrar e reconciliar a conta X”) se decompõe em fases de extração, transformação, validação e carregamento, com dependências entre passos.
+- **Tecnologia:** plano em DAG persistido num armazém duradouro; replanejamento entrelaçado perante falhas de validação; orçamentos de passos e de custo.
+- **Carga:** tarefas de horizonte longo que abrangem de minutos a horas, com dezenas de passos cada uma.
+- **Resultados (representativos):** externalizar o plano e acrescentar replanejamento limitado costuma elevar substancialmente a taxa de conclusão de tarefa diante de uma linha de base de planejar uma só vez, em tarefas com taxas de falha realistas, sobretudo por recuperar localmente de falhas transitórias em vez de abortar a execução inteira.
+
+### Lições aprendidas
+
+Os maiores ganhos de confiabilidade não vêm de planos iniciais mais inteligentes, mas de um **replanejamento barato e bem limitado** e de **orçamentos de terminação explícitos**. Os agentes sem limite falham iterando; os agentes limitados falham em segurança e escalam.
+
+## Modos de falha observados
+
+| Modo de falha | Gatilho | Mitigação |
+|---|---|---|
+| Perda do plano numa queda | O plano só vive no contexto | Persistir o plano como estado duradouro |
+| Ciclo infinito | Sem orçamento de terminação | Orçamentos de passos, tempo e custo, mais limite de replanejamento |
+| Sobredecomposição | O objetivo é partido em microtarefas triviais | Ajustar a granularidade do passo às chamadas a ferramenta |
+| Replanejamento em ciclo | Redecomposição completa perante cada falha menor | Reparação local limitada antes de replanejar globalmente |
+| Conclusão por verificar | O modelo afirma ter terminado sem verificar os critérios | Verificação explícita dos critérios de sucesso |
+| Violação de dependências | Um passo é executado antes de sua pré-condição se verificar | Ordem do DAG imposta pelo orquestrador |
+
+## KPIs
+
+| Métrica | Objetivo | Notas |
+|---|---|---|
+| Taxa de conclusão de tarefa | Alta | Ao nível do objetivo, com critérios verificados |
+| Passos por tarefa | Mínimos | Menos é mais barato; vigiar a sobredecomposição |
+| Taxa de replanejamento | Baixa ou moderada | Os picos assinalam planos frágeis ou ferramentas instáveis |
+| Sucesso de recuperação do plano | Alto | Fração de falhas reparadas sem abortar |
+| Taxa de incumprimento de orçamento | → 0 | Tarefas que batem nos tetos de passos ou custo |
+
+## Métricas de custo
+
+- O **custo por tarefa** escala com passos × inferência por passo + custo de ferramentas; a sobredecomposição inflaciona-o diretamente.
+- **Sobrecusto de planejamento:** o planejamento entrelaçado acrescenta uma chamada de inferência por passo; planejar e depois executar amortiza uma única chamada de planejamento por muitos passos.
+- **Custo de replanejamento:** cada replanejamento é inferência adicional; o limite de replanejamento limita o custo no pior caso por tarefa.
+
+## Características de escalabilidade
+
+Os planos em DAG escalam o débito de execução ao expor ao orquestrador os ramos paralelizáveis. A complexidade do plano escala o custo de inferência de planejamento de forma superlinear, portanto a decomposição hierárquica (planejar fases de forma grosseira e expandir preguiçosamente) mantém limitado o custo de planejamento por tarefa à medida que os objetivos crescem. O estado duradouro do plano escala com o número de objetivos concorrentes em andamento, não com sua duração, o que faz do armazém de estado o componente a dimensionar para a concorrência.
+
+## Conteúdo relacionado
+
+- HRN-003 — Onde encaixa o planejamento na taxonomia do harness.
+- HRN-010 — A orquestração executa o plano e despacha os ramos paralelos.
+- PAT-010 — Padrão de decomposição de objetivos.
+
+## Referências
+
+- Yao et al., “ReAct: Synergizing Reasoning and Acting in Language Models”.
+- Wang et al., “Plan-and-Solve Prompting”.
+- Planejamento clássico em IA: literatura sobre STRIPS e HTN (redes hierárquicas de tarefas).
+
+## Perguntas frequentes
+
+**P: O plano deve viver na janela de contexto?**
+R: Não. Persista-o como estado duradouro. O contexto é volátil, limitado em dimensão e ingovernável; um plano persistido é retomável, inspecionável e auditável.
+
+**P: Planejar e depois executar, ou entrelaçar?**
+R: Escolha consoante a tarefa. Os fluxos deterministas favorecem planejar e depois executar; as tarefas abertas ou propensas a falhar favorecem o replanejamento entrelaçado. O planejamento hierárquico mistura os dois.
+
+**P: Como evito que um agente itere para sempre?**
+R: Faça com que os critérios de terminação façam parte do objetivo: orçamentos de passos, tempo e custo mais um limite de replanejamento, com escalonamento para um humano ou supervisor perante o incumprimento.

package/content/harness/HRN-010-orchestration.es.md

@@ -0,0 +1,107 @@
+---
+title: "Orquestación"
+summary: "El bucle que gobierna el sistema: quién llama al modelo, con qué contexto, qué ocurre con la salida, y cómo se coordinan varios agentes sin perder control ni trazabilidad."
+---
+
+# Orquestación
+
+## Resumen ejecutivo
+
+La orquestación es la sala de máquinas del harness: la capa que decide *quién actúa, en qué orden y qué pasa cuando un paso falla*. Abarca desde un único agente ejecutando un bucle hasta flotas de agentes especializados coordinados por un supervisor. Este capítulo enmarca la orquestación como el puente entre un plan representado (HRN-009) y una ejecución fiable, y sostiene que el problema central de ingeniería no es la inteligencia sino la **durabilidad**: flujos de larga duración, no deterministas y con fallos parciales deben sobrevivir a las caídas, reanudarse limpiamente y no perder ni duplicar efectos en silencio. El valor por defecto correcto es la topología más simple que cumpla el requisito: la complejidad en la orquestación es un coste, no una virtud.
+
+## Conceptos clave
+
+- **Topología:** la disposición de los agentes: único, tubería, supervisor/trabajador o red.
+- **Agente supervisor u orquestador:** un agente que planifica y delega en trabajadores (véase PAT-002).
+- **Agente trabajador:** un agente especializado que ejecuta una subtarea delegada (véase PAT-005).
+- **Enrutado:** seleccionar el siguiente agente, herramienta o rama en función del estado.
+- **Máquina de estados:** un grafo explícito de estados y transiciones que gobierna la ejecución.
+- **Ejecución duradera:** semántica de flujo en la que el progreso se persiste en puntos de control y es reanudable.
+- **Traspaso (handoff):** transferir control y contexto de un agente a otro.
+
+## Definición
+
+> La **orquestación** es la disciplina del harness que ejecuta un plan a través de uno o varios agentes y herramientas: selecciona la topología, encamina el control, coordina el estado y garantiza una ejecución duradera y con exactamente el número correcto de repeticiones ante el fallo.
+
+## Explicación detallada
+
+La **selección de topología** es la primera decisión y la de mayor consecuencia. Un *agente único* con herramientas es el valor por defecto correcto para la mayoría de las tareas: es el más barato, el más fácil de observar y el que tiene menos modos de fallo por coordinación. Recurre al multiagente solo cuando la tarea se beneficie de verdad: cuando las subtareas necesiten permisos de herramienta *distintos*, ventanas de contexto *distintas* o ejecución *paralela* e independiente. Las topologías habituales son: **tubería** (secuencia fija de etapas), **supervisor/trabajador** (PAT-002 + PAT-005: un planificador delega en especialistas y agrega) y **red o pares** (los agentes se traspasan el control libremente). El coste de coordinación sube bruscamente con la libertad de la topología; las redes de pares son potentes pero las más difíciles de hacer fiables, de gobernar y de depurar.
+
+El **enrutado** es cómo se mueve el control por el sistema. Puede ser *dirigido por el modelo* (el supervisor elige el siguiente trabajador mediante llamada a herramienta), *dirigido por reglas* (transiciones deterministas en una máquina de estados) o *híbrido*. El enrutado determinista es preferible siempre que el camino se conozca, porque es gobernable y comprobable; el dirigido por el modelo se reserva para las ramificaciones genuinamente abiertas. Codificar el flujo como una **máquina de estados** explícita —estados, transiciones permitidas y guardas— es la técnica de fiabilidad de mayor palanca en orquestación: acota el espacio de comportamientos, hace el sistema inspeccionable y permite a la gobernanza (HRN-008) enganchar controles a las transiciones.
+
+La **durabilidad** es la propiedad que separa una demo de un sistema de producción. Los flujos agénticos son de larga duración (de segundos a horas), llaman a herramientas externas inestables y pueden caerse a mitad de vuelo. Un motor de ejecución duradera persiste el progreso tras cada paso, de modo que ante un fallo el flujo *se reanuda* desde el último paso completado en lugar de reiniciarse. Eso exige cuidado con la semántica de efectos: las llamadas a herramientas con efectos secundarios deben ser **idempotentes** o estar protegidas con claves de deduplicación, para que una reanudación no cobre dos veces una tarjeta ni reenvíe un correo. Los casos duros son los *efectos externos no idempotentes*; el harness los maneja con el patrón saga: registrar la intención, ejecutar, confirmar y ofrecer acciones compensatorias ante un fallo parcial.
+
+La **gestión de estado y contexto** entre agentes es donde los sistemas multiagente pierden fiabilidad. Cada traspaso (PAT-005) debe transferir *exactamente* el contexto que el trabajador necesita: de menos y falla; de más y sale caro y propenso a la distracción. El estado compartido pertenece a un almacén duradero con propiedad clara, no a una ventana de contexto compartida flotando libre. La agregación de las salidas de los trabajadores necesita un reductor explícito con resolución de conflictos, porque los trabajadores paralelos producirán resultados solapados o contradictorios.
+
+Por último, la orquestación es dueña de la **concurrencia y el aislamiento de fallos**. Las ramas paralelas (expuestas por el plan en DAG de HRN-009) mejoran la latencia, pero exigen contrapresión, coordinación de límites de tasa entre herramientas compartidas y compartimentación para que un trabajador que falla no agote el presupuesto ni bloquee a sus hermanos. Los tiempos de espera, los cortacircuitos y los presupuestos por trabajador son asuntos de la orquestación, no de la aplicación.
+
+## Evidencia de producción
+
+> **Escenario ilustrativo y representativo.** Nivel de evidencia: teórico · Confianza: media · Fuente: observación de industria, experiencia personal. Las cifras siguientes son rangos representativos, no una medición de un despliegue verificado concreto.
+
+- **Contexto:** un agente de investigación y síntesis que responde preguntas empresariales complejas.
+- **Escenario:** un supervisor descompone una pregunta, despacha trabajadores de recuperación y análisis en paralelo, y agrega una respuesta con citas.
+- **Tecnología:** motor de flujo duradero, topología supervisor/trabajador, enrutador determinista para las etapas conocidas, claves de deduplicación en las herramientas con efectos.
+- **Carga:** ejecuciones concurrentes de varios trabajadores; cada ejecución dura minutos y hace varias llamadas a herramientas externas.
+- **Resultados (representativos):** el abanico paralelo suele recortar la latencia de reloj en un múltiplo significativo frente a la ejecución secuencial, mientras que los puntos de control duraderos reducen la tasa de ejecuciones fallidas al eliminar los reinicios completos provocados por caídas. El coste es un mayor gasto en tokens (más agentes, más contexto) y una complejidad de coordinación añadida.
+
+### Lecciones aprendidas
+
+La mayoría de los equipos recurre al multiagente demasiado pronto. La progresión fiable es: hacer que funcione un agente único, codificarlo como máquina de estados, añadir durabilidad y *entonces* dividir en trabajadores solo allí donde el paralelismo o el aislamiento de permisos compense el coste de coordinación.
+
+## Modos de fallo observados
+
+| Modo de fallo | Disparador | Mitigación |
+|---|---|---|
+| Efectos secundarios duplicados | La reanudación reejecuta un paso no idempotente | Claves de idempotencia / compensación saga |
+| Progreso perdido en una caída | Sin puntos de control | Motor de ejecución duradera |
+| Pérdida de contexto en el traspaso | El trabajador recibe menos estado del necesario | Contratos de traspaso explícitos y tipados |
+| Interbloqueo de coordinación | Los trabajadores se esperan mutuamente | Enrutado acíclico, tiempos de espera, arbitraje del supervisor |
+| Explosión de coste | Delegación recursiva o entre pares sin límite | Presupuesto de agentes por ejecución + tope de profundidad de delegación |
+| Agregación contradictoria | Los trabajadores paralelos discrepan | Reductor explícito con resolución de conflictos |
+| Estrangulamiento de herramienta compartida | Los trabajadores martillean una API con límite de tasa | Límite de tasa centralizado + contrapresión |
+
+## KPIs
+
+| Métrica | Objetivo | Notas |
+|---|---|---|
+| Tasa de finalización de tarea | Alta | De extremo a extremo, verificada |
+| Latencia p50/p95/p99 | Minimizada | El paralelismo mejora p50; las colas las dominan los trabajadores lentos |
+| Tasa de éxito de reanudación | → 100 % | Flujos que se recuperan tras una caída |
+| Tasa de efectos duplicados | → 0 | Corrección de la idempotencia |
+| Coste por tarea | Acotado | Topes de agentes, profundidad y tokens |
+| Rendimiento | Escala con la concurrencia | Limitado por los límites de tasa de las herramientas compartidas |
+
+## Métricas de coste
+
+- El **coste en tokens** crece con el número de agentes y el contexto por agente; el multiagente es materialmente más caro que el agente único para la misma tarea.
+- **Sobrecoste de orquestación:** inferencia de planificación del supervisor más la de agregación por ejecución.
+- **Sobrecoste de durabilidad:** las escrituras de punto de control (baratas) frente al gran ahorro de no reiniciar las ejecuciones fallidas.
+
+## Características de escalado
+
+El rendimiento del agente único escala horizontalmente y sin estado. El supervisor/trabajador escala las subtareas en paralelo hasta los límites de tasa de las herramientas compartidas, que se convierten en el techo real. Los motores de flujo duradero escalan con el número de flujos en vuelo; el almacenamiento de puntos de control y el despachador son los componentes que hay que dimensionar. Las topologías de red o pares son las que peor escalan: el sobrecoste de coordinación y la superficie de fallo crecen de forma superlineal con el número de agentes, y por eso las topologías de supervisor acotadas son el valor por defecto en la empresa.
+
+## Contenido relacionado
+
+- HRN-003 — El lugar de la orquestación en la taxonomía del harness.
+- HRN-009 — El plan que la orquestación ejecuta.
+- PAT-002 — Patrón de agente supervisor.
+- PAT-005 — Patrón de delegación multiagente.
+
+## Referencias
+
+- Temporal y otros motores de flujo de ejecución duradera (patrón saga, durabilidad de flujos).
+- Anthropic, «Building Effective Agents» (agente único primero, guía de topologías).
+- LangGraph y la orquestación por máquina de estados para agentes.
+
+## Preguntas frecuentes
+
+**P: ¿Agente único o multiagente?**
+R: Por defecto, agente único. Añade agentes solo por paralelismo o por aislamiento de permisos o contexto que compense el coste de coordinación.
+
+**P: ¿Por qué una máquina de estados en lugar de bucles de agente libres?**
+R: Las máquinas de estados acotan el comportamiento, son comprobables y permiten a la gobernanza enganchar controles a las transiciones. Los bucles libres son potentes, pero difíciles de hacer fiables o auditables.
+
+**P: ¿Cómo evito cobrar dos veces a un cliente en un reintento?**
+R: Haz idempotentes las llamadas a herramientas con efectos (claves de deduplicación) o envuélvelas en una saga con acciones compensatorias, y ejecútalas sobre un motor duradero que reanude en lugar de reiniciar.