izanagi-ai 2.9.4 → 2.9.5

package/.manifest

@@ -1,12 +1,32 @@
 {
   "name": "izanagi-ai",
-  "version": "2.9.4",
+  "version": "2.9.5",
   "description": "Izanagi AI - Modular Skill-Oriented AI Prompt & Agent Framework for Autonomous Software Engineering",
   "author": "Pedro Henrique Sanches Leal",
   "license": "MIT",
   "homepage": "https://github.com/pedrohenriquesanchesleal4-debug/izanagi-ai#readme",
-  "generatedAt": "2026-08-11T12:04:25.684Z",
+  "generatedAt": "2026-08-11T12:46:08.320Z",
   "agents": [
+    {
+      "id": "adversarial-critic",
+      "name": "Adversarial Critic",
+      "version": "1.0.0",
+      "file": "agents/adversarial-critic-agent.json",
+      "role": "Crítica adversarial de implementações: caçar bugs, falhas de segurança, problemas de arquitetura, requisitos faltantes, problemas de performance, edge cases, suposições incorretas, overengineering e AI slop",
+      "skills": [
+        "code-auditor",
+        "security-privacy",
+        "anti-ai-slop",
+        "complexity-analyzer",
+        "qa",
+        "self-critique"
+      ],
+      "chains": [
+        "critique_code",
+        "critique_ui",
+        "critique_architecture"
+      ]
+    },
     {
       "id": "animation",
       "name": "Animation Engineer",
@@ -205,6 +225,25 @@
         "diagram"
       ]
     },
+    {
+      "id": "evaluator",
+      "name": "Evaluator",
+      "version": "1.0.0",
+      "file": "agents/evaluator-agent.json",
+      "role": "Avaliação estruturada de resultados de agentes e workflows: score por métricas, verdict (PASS/PASS_WITH_WARNINGS/FAIL/BLOCKED/UNKNOWN), detecção de regressões e recomendações acionáveis",
+      "skills": [
+        "qa",
+        "confidence-estimator",
+        "code-auditor",
+        "self-critique",
+        "memoria-projeto"
+      ],
+      "chains": [
+        "evaluate_code",
+        "evaluate_architecture",
+        "evaluate_automation"
+      ]
+    },
     {
       "id": "form-engineer",
       "name": "Form & UI Engineer",
@@ -290,6 +329,25 @@
         "regression"
       ]
     },
+    {
+      "id": "researcher",
+      "name": "Researcher",
+      "version": "1.0.0",
+      "file": "agents/researcher-agent.json",
+      "role": "Pesquisa estruturada baseada em evidência: coleta de fatos com fontes citadas, distinção FACT/ASSUMPTION/INFERENCE/UNKNOWN, priorização de fontes oficiais e relatório com nível de confiança",
+      "skills": [
+        "deep-research",
+        "confidence-estimator",
+        "hallucination-detection",
+        "documentation-writer",
+        "memoria-projeto"
+      ],
+      "chains": [
+        "research_stack",
+        "research_market",
+        "research_technical"
+      ]
+    },
     {
       "id": "security",
       "name": "Security Engineer",
@@ -368,7 +426,7 @@
   "skills": [
     {
       "name": "Skill Library",
-      "count": 142,
+      "count": 146,
       "skills": [
         {
           "id": "a11y",
@@ -382,6 +440,12 @@
           "version": "1.0.0",
           "path": "skills/accessibility-reviewer/SKILL.md"
         },
+        {
+          "id": "adversarial-critic",
+          "name": "adversarial-critique",
+          "version": "1.0.0",
+          "path": "skills/adversarial-critique/SKILL.md"
+        },
         {
           "id": "agentic-coding",
           "name": "agentic-coding",
@@ -472,6 +536,12 @@
           "version": "1.0.0",
           "path": "skills/automation-security/SKILL.md"
         },
+        {
+          "id": "avaliacao",
+          "name": "evaluation",
+          "version": "1.0.0",
+          "path": "skills/evaluation/SKILL.md"
+        },
         {
           "id": "brainstorming",
           "name": "brainstorming",
@@ -712,6 +782,12 @@
           "version": "1.0.0",
           "path": "skills/error-recovery/SKILL.md"
         },
+        {
+          "id": "failure-patterns",
+          "name": "failure-patterns",
+          "version": "1.0.0",
+          "path": "skills/failure-patterns/SKILL.md"
+        },
         {
           "id": "fan-out",
           "name": "Parallel Agents (Fan-Out & Swarm Orc",
@@ -754,6 +830,12 @@
           "version": "1.0.0",
           "path": "skills/hallucination-detection/SKILL.md"
         },
+        {
+          "id": "handoff",
+          "name": "handoff-protocol",
+          "version": "1.0.0",
+          "path": "skills/handoff-protocol/SKILL.md"
+        },
         {
           "id": "handoff-sessao",
           "name": "handoff-sessao",

package/agents/adversarial-critic-agent.json

@@ -0,0 +1,53 @@
+{
+  "name": "Adversarial Critic",
+  "version": "1.0.0",
+  "role": "Crítica adversarial de implementações: caçar bugs, falhas de segurança, problemas de arquitetura, requisitos faltantes, problemas de performance, edge cases, suposições incorretas, overengineering e AI slop",
+  "identity": "Você é o ADVERSARIAL CRITIC do Izanagi AI. Sua única função é TENTAR QUEBRAR a implementação — você não implementa. Você procura ativamente por problemas antes que eles cheguem à produção.\n\nO QUE PROCURAR (checklist adversarial):\n1. BUGS: condições de corrida, null/undefined, off-by-one, estados inconsistentes, async mal tratado, memory leaks.\n2. SEGURANÇA: injection (SQL/XSS/command), auth quebrada, secrets expostos, IDOR, SSRF, CORS errado, headers ausentes.\n3. ARQUITETURA: acoplamento, camadas violadas, dependências circulares, teste de configuração na lógica.\n4. REQUISITOS FALTANTES: requisitos do pedido que não foram implementados ou implementados pela metade.\n5. PERFORMANCE: N+1, loops O(n²), renderizações desnecessárias, assets pesados.\n6. EDGE CASES: input vazio, valores extremos, unicodde, timezone, locale, concorrência.\n7. SUPOSIÇÕES INCORRETAS: premissas sobre o ambiente, dados, comportamento de terceiros.\n8. OVERENGINEERING: abstrações desnecessárias, complexidade sem retorno.\n9. AI SLOP: UI genérica, copy clichê, padrões de design robóticos.\n\nFORMATO DE SAÍDA:\nPara cada problema: severidade (CRITICAL/HIGH/MEDIUM/LOW), arquivo+linha quando aplicável, descrição do impacto e sugestão de correção concreta. No final: veredicto de prontidão (READY / READY_WITH_FIXES / NOT_READY) e lista priorizada de fixes.\n\nREGRAS:\n- Você NÃO corrige: apenas aponta com precisão. Quem corrige é o senior-engineer.\n- Não reporte problemas inexistentes por vaidade: cada finding deve ter justificativa técnica.\n- Não aceite 'funciona na minha máquina': questione portabilidade, produtividade e produção.",
+  "token_budget": 4000,
+  "model": "claude-sonnet-4-20250514",
+  "skills": [
+    "code-auditor",
+    "security-privacy",
+    "anti-ai-slop",
+    "complexity-analyzer",
+    "qa",
+    "self-critique"
+  ],
+  "chains": {
+    "critique_code": ["memoria-projeto", "code-auditor", "security-privacy", "anti-ai-slop", "qa", "memoria-projeto"],
+    "critique_ui": ["memoria-projeto", "anti-ai-slop", "ux-reviewer", "accessibility-reviewer", "qa", "memoria-projeto"],
+    "critique_architecture": ["memoria-projeto", "architecture-patterns", "code-auditor", "qa", "memoria-projeto"]
+  },
+  "capabilities": [
+    "caça de bugs e edge cases",
+    "análise de segurança ofensiva (white-box)",
+    "detecção de AI slop e overengineering",
+    "validação de cobertura de requisitos",
+    "priorização de fixes por severidade"
+  ],
+  "inputs": ["implementação a criticar", "requisitos originais"],
+  "outputs": ["critique report (findings com severidade + veredicto)"],
+  "constraints": [
+    "Nunca implementar correções — somente apontar problemas",
+    "Cada finding exige justificativa técnica, sem achismo",
+    "Não inflar relatório com problemas triviais"
+  ],
+  "handoffs": [
+    { "to": "senior-engineer", "reason": "aplicar_fixes" },
+    { "to": "evaluator", "reason": "avaliacao_final" },
+    { "to": "security", "reason": "aprofundar_vulnerabilidades" }
+  ],
+  "memory": ["memoria-projeto", "handoff-sessao"],
+  "evaluation": { "metrics": ["correctness", "security", "performance"], "minScore": 0.75 },
+  "compatibility": ">=3.0.0",
+  "always": [
+    "Emitir veredicto claro (READY / READY_WITH_FIXES / NOT_READY) com lista priorizada de fixes",
+    "Classificar cada finding por severidade com impacto técnico concreto",
+    "Verificar cobertura de TODOS os requisitos do pedido original"
+  ],
+  "never": [
+    "Implementar ou corrigir o código criticado",
+    "Reportar problemas sem justificativa técnica",
+    "Ignorar problemas de segurança por 'baixa probabilidade'"
+  ]
+}

package/agents/evaluator-agent.json

@@ -0,0 +1,52 @@
+{
+  "name": "Evaluator",
+  "version": "1.0.0",
+  "role": "Avaliação estruturada de resultados de agentes e workflows: score por métricas, verdict (PASS/PASS_WITH_WARNINGS/FAIL/BLOCKED/UNKNOWN), detecção de regressões e recomendações acionáveis",
+  "identity": "Você é o EVALUATOR do Izanagi AI. Sua única função é AVALIAR — nunca implementar. Recebe artefatos de outros agentes (código, arquitetura, schema, relatório) e produz um Evaluation Report estruturado.\n\nMÉTODO:\n1. MÉTRICAS em escala 0-1 por dimensão: correctness (0.3), requirementCoverage (0.15), testResults (0.2), architecture (0.1), security (0.1), performance (0.05), maintainability (0.05), artifactValidity (0.05).\n2. VERDICT derivado: score >= 0.85 → PASS; >= 0.70 → PASS_WITH_WARNINGS; regressões ou testes falhando ou score < 0.70 → FAIL; falha estrutural sem nenhum teste passando → BLOCKED.\n3. REGRESSÕES: liste qualquer comportamento que tenha piorado em relação ao estado anterior.\n4. RECOMENDAÇÕES: ações concretas e ordenadas por impacto para subir o score.\n5. CONFIDENCE: reporte quanto da avaliação é baseado em evidência real (build, testes) vs suposição.\n\nREGRAS:\n- Evidência > afirmação: se o produtor afirma que build passou, exija o log.\n- Nunca edite o artefato avaliado. A saída é somente o report.\n- Contrato de saída: JSON estruturado com taskId, verdict, score, confidence, metrics, tests, regressions, recommendations.",
+  "token_budget": 4000,
+  "model": "claude-sonnet-4-20250514",
+  "skills": [
+    "qa",
+    "confidence-estimator",
+    "code-auditor",
+    "self-critique",
+    "memoria-projeto"
+  ],
+  "chains": {
+    "evaluate_code": ["memoria-projeto", "code-auditor", "confidence-estimator", "qa", "memoria-projeto"],
+    "evaluate_architecture": ["memoria-projeto", "requirement-analyzer", "confidence-estimator", "qa", "memoria-projeto"],
+    "evaluate_automation": ["memoria-projeto", "testing-automation", "confidence-estimator", "qa", "memoria-projeto"]
+  },
+  "capabilities": [
+    "avaliação por métricas ponderadas",
+    "detecção de regressões",
+    "verdict estruturado",
+    "recomendações acionáveis",
+    "auditoria de evidência (logs de build/testes)"
+  ],
+  "inputs": ["artefato a avaliar", "requisitos originais", "evidência de verificação"],
+  "outputs": ["evaluation report JSON"],
+  "constraints": [
+    "Nunca implementar ou corrigir código — somente avaliar",
+    "Nunca inventar métricas sem evidência",
+    "Sempre reportar confidence real da avaliação"
+  ],
+  "handoffs": [
+    { "to": "senior-engineer", "reason": "correcao_apos_falha" },
+    { "to": "techlead", "reason": "revisao_de_arquitetura" },
+    { "to": "qa", "reason": "testes_complementares" }
+  ],
+  "memory": ["memoria-projeto", "handoff-sessao"],
+  "evaluation": { "metrics": ["correctness", "testResults", "confidence"], "minScore": 0.8 },
+  "compatibility": ">=3.0.0",
+  "always": [
+    "Produzir Evaluation Report estruturado (verdict, score, confidence, metrics, tests, regressions, recommendations)",
+    "Exigir evidência real (logs de build/testes) antes de aceitar claims de sucesso",
+    "Registrar padrões de falha na memória quando detectar regressões"
+  ],
+  "never": [
+    "Implementar, corrigir ou refatorar o artefato avaliado",
+    "Reportar métricas não medidas como medidas",
+    "Emitir PASS sem verificar os critérios mínimos (score >= 0.85, zero testes falhando)"
+  ]
+}

package/agents/researcher-agent.json

@@ -0,0 +1,52 @@
+{
+  "name": "Researcher",
+  "version": "1.0.0",
+  "role": "Pesquisa estruturada baseada em evidência: coleta de fatos com fontes citadas, distinção FACT/ASSUMPTION/INFERENCE/UNKNOWN, priorização de fontes oficiais e relatório com nível de confiança",
+  "identity": "Você é o RESEARCHER do Izanagi AI. Transforma research em artefato estruturado, nunca em achismo.\n\nMÉTODO:\n1. PLANO DE BUSCA: defina queries por subtema antes de buscar.\n2. COLETA: para cada claim, registre fonte, tipo de fonte e data de verificação.\n3. CLASSIFICAÇÃO de cada claim importante:\n   - FACT: confirmado em fonte oficial/documentação/source code/testes.\n   - ASSUMPTION: razoável mas não confirmada.\n   - INFERENCE: derivada de fatos, com cadeia lógica explícita.\n   - UNKNOWN: não foi possível verificar.\n4. PRIORIDADE DE FONTES: documentação oficial > source code > testes > package metadata > fontes técnicas confiáveis > comunidades.\n5. RELATÓRIO: seções por questão de pesquisa, claims com [claim | source | confidence | sourceType | verifiedAt], síntese e recomendações com nível de confiança.\n\nREGRAS:\n- Nunca invente URLs ou fontes. Se não encontrou, marque UNKNOWN.\n- Nunca apresente AS inference como FACT.\n- Nunca cola direta: sintetize com atribuição.\n- Sempre reporte limitações: o que não foi verificado e por quê.",
+  "token_budget": 5000,
+  "model": "claude-sonnet-4-20250514",
+  "skills": [
+    "deep-research",
+    "confidence-estimator",
+    "hallucination-detection",
+    "documentation-writer",
+    "memoria-projeto"
+  ],
+  "chains": {
+    "research_stack": ["memoria-projeto", "deep-research", "confidence-estimator", "documentation-writer", "memoria-projeto"],
+    "research_market": ["memoria-projeto", "deep-research", "confidence-estimator", "memoria-projeto"],
+    "research_technical": ["memoria-projeto", "deep-research", "hallucination-detection", "confidence-estimator", "memoria-projeto"]
+  },
+  "capabilities": [
+    "plano de busca multi-query",
+    "classificação FACT/ASSUMPTION/INFERENCE/UNKNOWN",
+    "citação com fonte + confiança + data de verificação",
+    "síntese com limitações explícitas",
+    "detecção de alucinação em fontes"
+  ],
+  "inputs": ["questão de pesquisa", "domínio"],
+  "outputs": ["research artifact (claims classificados + fontes + confiança)"],
+  "constraints": [
+    "Nunca inventar fontes ou URLs",
+    "Nunca apresentar inferências como fatos",
+    "Sempre reportar limitações e nível de confiança"
+  ],
+  "handoffs": [
+    { "to": "architect", "reason": "decisao_arquitetural_baseada_em_evidencia" },
+    { "to": "discovery", "reason": "viabilidade_de_produto" },
+    { "to": "evaluator", "reason": "avaliacao_do_relatorio" }
+  ],
+  "memory": ["memoria-projeto", "handoff-sessao"],
+  "evaluation": { "metrics": ["correctness", "confidence", "requirementCoverage"], "minScore": 0.75 },
+  "compatibility": ">=3.0.0",
+  "always": [
+    "Classificar cada claim importante como FACT/ASSUMPTION/INFERENCE/UNKNOWN",
+    "Citar fonte + tipo + confiança + data de verificação para claims críticos",
+    "Priorizar documentação oficial, source code e testes"
+  ],
+  "never": [
+    "Inventar URLs, citações ou dados",
+    "Apresentar suposições como fatos verificados",
+    "Entregar relatório sem seção de limitações"
+  ]
+}

package/core/evaluation-engine.md

@@ -0,0 +1,64 @@
+# Evaluation Engine
+
+> Status: **IMPLEMENTED** — `src/runtime/evaluation/engine.ts` + `src/runtime/contracts/artifacts.ts`
+> Versão: 3.0.0 | Compatibilidade: >= 2.0.0
+
+## Propósito
+
+Avaliar resultados de agentes e workflows com métricas estruturadas e verdict derivado por thresholds. O Evaluation Engine é a primitiva que alimenta decisões de self-healing, learning e relatórios de benchmark.
+
+## Verdicts
+
+| Verdict | Critério |
+|---|---|
+| `PASS` | score >= 0.85, zero testes falhando, zero regressões |
+| `PASS_WITH_WARNINGS` | score >= 0.70, ou testes pulados |
+| `FAIL` | testes falhando, regressões, ou score < 0.70 |
+| `BLOCKED` | falha estrutural sem nenhum teste passando |
+| `UNKNOWN` | sem evidência suficiente |
+
+## Métricas (ponderação padrão)
+
+| Métrica | Peso |
+|---|---|
+| correctness | 0.30 |
+| testResults | 0.20 |
+| requirementCoverage | 0.15 |
+| architecture | 0.10 |
+| security | 0.10 |
+| performance | 0.05 |
+| maintainability | 0.05 |
+| artifactValidity | 0.05 |
+
+Métricas não medidas são ignoradas na ponderação (não penalizam), mas reduzem a `confidence` da avaliação.
+
+## Contrato de saída
+
+```json
+{
+  "taskId": "...",
+  "success": true,
+  "score": 0.94,
+  "confidence": 0.91,
+  "metrics": { "correctness": 0.96, "security": 0.93 },
+  "tests": { "passed": 42, "failed": 0 },
+  "regressions": [],
+  "recommendations": []
+}
+```
+
+## Artefatos & Validação
+
+Schemas em `src/runtime/contracts/artifacts.ts` para: `requirements`, `architecture`, `database-schema`, `api-contract`, `security-report`, `test-plan`, `implementation-plan`, `evaluation`, `research`, `trace`. Validação detecta stubs (`TODO`, `FIXME`, `implement later`), campos obrigatórios ausentes e tamanho mínimo. Artefato inválido → `INVALID → REPAIR → RE-EVALUATE`.
+
+## CLI
+
+```bash
+izanagi eval <file.json>            # avalia métricas de um artefato JSON
+izanagi eval --metrics correctness=0.9,security=0.8
+izanagi eval --report <run-id>      # avaliação registrada de um run
+```
+
+## Testes
+
+`src/runtime/tests/evaluation.test.ts` — cobertura: weighted score, verdicts, testMetrics, confidence, thresholds custom.

package/core/execution-graph.md

@@ -0,0 +1,60 @@
+# Execution Graph & Orchestration
+
+> Status: **IMPLEMENTED** — `src/runtime/orchestration/graph.ts`, `planner.ts`, `orchestrator.ts`
+> Versão: 3.0.0 | Compatibilidade: >= 2.0.0
+
+## Propósito
+
+Transformar cada execução complexa em um grafo explícito, construído dinamicamente conforme a tarefa — nunca workflows gigantes estáticos.
+
+## Node
+
+```json
+{
+  "id": "architecture",
+  "kind": "agent",
+  "agent": "architect",
+  "skills": ["architecture-patterns"],
+  "inputs": ["requirements"],
+  "outputs": ["architecture"],
+  "dependencies": ["discovery"],
+  "retryPolicy": { "maxAttempts": 2, "backoffMs": 500 },
+  "timeoutMs": 300000,
+  "tokenBudget": 4000,
+  "validator": "architecture"
+}
+```
+
+Kinds: `agent`, `skill`, `tool`, `validator`, `evaluator`, `aggregator`, `parallel`, `gate`.
+
+## Templates (planner)
+
+| Template | Grafo |
+|---|---|
+| `fullstack` | discovery → architect → (security ∥ database ∥ product) → senior-engineer → (qa-gate ∥ critic) → evaluation |
+| `debugging` | reproduce → root-cause → fix → regression-test → evaluation |
+| `security_audit` | scan → deep-analysis → remediation → critic → evaluation |
+| `architecture` | research → design → adr → evaluation |
+| `automacao` | plan → build → test → evaluation |
+| `frontend` | design-direction → design-system → implementation → (perf-check ∥ critic) → evaluation |
+| `implementation` | execute → verify → evaluation |
+
+## Paralelismo
+
+O planner detecta dependências e computa `parallelBatches`: nós sem dependência mútua executam em paralelo, `aggregator` combina resultados.
+
+## Orçamento global
+
+`maxAttempts` (3), `maxTokens` (32k), `maxTimeMs` (900s) — impede loops infinitos.
+
+## CLI
+
+```bash
+izanagi workflow list                    # templates + composições
+izanagi workflow inspect fullstack       # detalha um grafo
+izanagi run "tarefa" --runtime           # executa via Orchestrator (graph + eval + trace)
+```
+
+## Testes
+
+`src/runtime/tests/graph.test.ts` — cobertura: ordem topológica, batches paralelos, detecção de ciclo, subgraph, replan.

package/core/model-router.md

@@ -0,0 +1,64 @@
+# Model Router & Adaptive Routing
+
+> Status: **IMPLEMENTED** — `src/runtime/model/router.ts`, `src/runtime/routing/scorer.ts`, `resolver.ts`
+> Versão: 3.0.0 | Compatibilidade: >= 2.0.0
+
+## Propósito
+
+O Izanagi não depende conceitualmente de um único provider. O Model Router seleciona o modelo por complexidade da tarefa, exigência de raciocínio, risco, custo, latência, janela de contexto e histórico de performance. Tarefa simples nunca consome modelo caro desnecessariamente.
+
+## Providers
+
+Catálogo default: OpenAI (gpt-4o-mini / gpt-4o / gpt-4.1), Anthropic (claude-haiku-4-5 / claude-sonnet-4-5 / claude-opus-4-1), Google (gemini-2.0-flash / gemini-2.5-pro). Extensível via config do projeto.
+
+## Tiers
+
+`fast` (simples, barato, rápido) · `balanced` (default) · `premium` (raciocínio alto, risco alto, contexto gigante).
+
+## Routing Context
+
+```json
+{
+  "task": "...",
+  "taskComplexity": 1-5,
+  "reasoningRequirement": "low|medium|high",
+  "risk": 0.2,
+  "tokenBudget": 16000,
+  "requiresTools": false,
+  "historicalPerformance": {}
+}
+```
+
+## Candidate Scoring
+
+```json
+{
+  "candidate": "database-agent",
+  "relevance": 0.97,
+  "historicalSuccess": 0.93,
+  "compatibility": 1,
+  "risk": 0.08,
+  "cost": 0.31,
+  "finalScore": 0.91
+}
+```
+
+Pesos: relevance 0.40, historicalSuccess 0.20, compatibility 0.15, risk 0.10, cost 0.10, latency 0.05.
+
+Relevância semântica: tokenização + overlap de termos (sem dependências externas, determinística).
+
+## Agent Genome & Skill Manifest
+
+- Agentes: `name, version, purpose, capabilities, requiredSkills, optionalSkills, inputs, outputs, constraints, permissions, handoffs, memory, evaluation, tokenBudget, compatibility` (+ campos legacy preservados).
+- Skills: `name, version, description, capabilities, triggers, dependencies, inputs, outputs, permissions, compatibility, risk, tokenBudget, evaluation, examples, changelog` — parseados do frontmatter.
+
+## CLI
+
+```bash
+izanagi agent list | inspect <name>
+izanagi skill list | search <q> | inspect <name>
+```
+
+## Testes
+
+`src/runtime/tests/routing.test.ts` — cobertura: scoring, relevância semântica, rank de skills/agentes, model routing.

package/core/self-healing.md

@@ -0,0 +1,62 @@
+# Self-Healing & Failure Memory
+
+> Status: **IMPLEMENTED** — `src/runtime/recovery/healing.ts`, `src/runtime/memory/store.ts`
+> Versão: 3.0.0 | Compatibilidade: >= 2.0.0
+
+## Propósito
+
+Classificar falhas e aplicar a estratégia de recuperação correta, com limites rígidos para impedir loops infinitos. Falhas são transformadas em padrões reutilizáveis consultados antes de cada execução.
+
+## Classificação de falhas
+
+| Tipo | Exemplo | Estratégia |
+|---|---|---|
+| `recoverable` | timeout, 429, 5xx | retry com backoff exponencial |
+| `validation` | artefato fora do contrato | skill replacement corretivo + retry |
+| `planning` | grafo cíclico | replan (reconstrói grafo) |
+| `tool` | comando falhou | handoff para devops ou retry |
+| `agent` | saída inconsistente | handoff para techlead |
+| `dependency` | módulo ausente | handoff para bug-hunter |
+| `non-recoverable` | falha estrutural | abort com relatório |
+
+## Pipeline
+
+```text
+Failure → Classification → Padrão conhecido? → SIM: local repair guiado
+                                → NÃO: transitória → retry (backoff)
+                                → NÃO: validação → skill replacement
+                                → NÃO: planejamento → replan
+                                → NÃO: demais → handoff / abort
+```
+
+Limites: `maxAttempts`, `maxTokens`, `maxTime` — excedeu qualquer um → abort.
+
+## Failure Memory
+
+Categorias: `episodic`, `semantic`, `procedural`, `decision`, `failure`, `skill`, `project`.
+
+Padrão de falha (`.izanagi/state/runtime-state.json`):
+
+```json
+{
+  "pattern": "NEXT-HYDRATION-017",
+  "symptoms": ["Cannot read properties of null"],
+  "rootCause": "acesso a window no SSR",
+  "solution": "guard typeof window",
+  "confidence": 0.94,
+  "occurrences": 3
+}
+```
+
+`findRelevantFailures(query)` é consultado antes de toda execução — solução conhecida aplicada imediatamente.
+
+## CLI
+
+```bash
+izanagi memory inspect       # estado da memória (patterns, learnings, stats)
+izanagi memory search <q>    # busca nas categorias markdown
+```
+
+## Testes
+
+`src/runtime/tests/healing.test.ts`, `memory.test.ts` — cobertura: classificação, limites, consolidação de padrões, relevância.

package/core/skill-resolver.json

@@ -238,7 +238,17 @@
     "layered-security": "skills/defense-in-depth/SKILL",
     "systematic-debugging": "skills/systematic-debugging/SKILL",
     "debug-6-fases": "skills/systematic-debugging/SKILL",
-    "six-phase-debug": "skills/systematic-debugging/SKILL"
+    "six-phase-debug": "skills/systematic-debugging/SKILL",
+    "evaluation": "skills/evaluation/SKILL",
+    "evaluator": "skills/evaluation/SKILL",
+    "avaliacao": "skills/evaluation/SKILL",
+    "adversarial-critique": "skills/adversarial-critique/SKILL",
+    "critic": "skills/adversarial-critique/SKILL",
+    "adversarial-critic": "skills/adversarial-critique/SKILL",
+    "handoff-protocol": "skills/handoff-protocol/SKILL",
+    "handoff": "skills/handoff-protocol/SKILL",
+    "failure-patterns": "skills/failure-patterns/SKILL",
+    "padroes-falha": "skills/failure-patterns/SKILL"
   },
   "compositions": {
     "web_cinematic": {
@@ -506,6 +516,43 @@
         "professor-modo"
       ],
       "artifact": "execucao paralela de agentes com merge unificado"
+    },
+    "evaluated_delivery": {
+      "triggers": [
+        "entrega avaliada",
+        "com avaliacao",
+        "verificar antes de entregar",
+        "criticar implementacao",
+        "quality gate",
+        "entrega com nota"
+      ],
+      "chain": [
+        "evaluation",
+        "adversarial-critique",
+        "handoff-protocol",
+        "failure-patterns",
+        "memoria-projeto",
+        "qa"
+      ],
+      "artifact": "implementacao avaliada (score + verdict + regressoes + recomendacoes)"
+    },
+    "research_evidence": {
+      "triggers": [
+        "pesquisar",
+        "evidencia",
+        "fontes",
+        "comparar stacks",
+        "fatos",
+        "relatorio de pesquisa"
+      ],
+      "chain": [
+        "deep-research",
+        "confidence-estimator",
+        "hallucination-detection",
+        "documentation-writer",
+        "memoria-projeto"
+      ],
+      "artifact": "research artifact com claims classificados (FACT/ASSUMPTION/INFERENCE/UNKNOWN)"
     }
   }
 }

package/core/tracing.md

@@ -0,0 +1,42 @@
+# Tracing & Observability
+
+> Status: **IMPLEMENTED** — `src/runtime/observability/tracer.ts`
+> Versão: 3.0.0 | Compatibilidade: >= 2.0.0
+
+## Propósito
+
+Cada execução registra em `.izanagi/state/traces/<run-id>.json`:
+
+```text
+task, command, startedAt/endedAt, durationMs, model, tokens (in/out/total),
+retries, failures, agents, skills, tools, artifacts, evaluation (score/verdict),
+healing (ações), spans (task/decision/agent/skill/tool/model/evaluation/...),
+execution graph (nós + status + erro)
+```
+
+## CLI
+
+```bash
+izanagi trace                 # lista as últimas 20 execuções (run-id, verdict, score)
+izanagi trace <run-id>        # detalhe: spans, healing, graph, avaliação
+izanagi eval --report <run-id>  # só a avaliação
+```
+
+## Span
+
+```json
+{
+  "id": "3-model-router",
+  "name": "model-router:claude-sonnet-4-5",
+  "type": "decision",
+  "status": "ok",
+  "startedAt": "...",
+  "endedAt": "...",
+  "durationMs": 12,
+  "metadata": { "reasons": [] }
+}
+```
+
+## Testes
+
+`src/runtime/tests/tracer.test.ts` — cobertura: spans, persistência, listagem, runId.