izanagi-ai 2.9.5 → 2.10.0

package/.manifest

@@ -1,11 +1,11 @@
 {
   "name": "izanagi-ai",
-  "version": "2.9.5",
+  "version": "2.10.0",
   "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:46:08.320Z",
+  "generatedAt": "2026-08-11T14:02:38.028Z",
   "agents": [
     {
       "id": "adversarial-critic",

package/AGENTS.md

@@ -8,13 +8,13 @@
 
 ## 1. Visão Geral do Framework
 
-Izanagi AI é um **framework meta** para engenharia de software autônoma orientada a agentes: arquitetura em camadas (Decision → Context → Skill → Quality → Reflection → Memory), biblioteca de skills especializadas, **Skill Composer** (12 composições de skills encadeadas que se conversam), **14 agentes especializados** (incluindo o novo agente `/qa`), **Memória Persistente Anti-Repetição** (`.agents/memoria/`), **Curadoria de Referências** (`references/`), **Checkpoint & Self-Healing Swarm Engine**, e uma **CLI executável (`izanagi`)** publicada no npm (`izanagi-ai`). Este repositório É o framework (não um app que o usa).
+Izanagi AI é um **framework meta** para engenharia de software autônoma orientada a agentes: arquitetura em camadas (Routing → Orchestration → Evaluation → Healing → Memory), biblioteca de skills especializadas, **Skill Composer** (15 composições de skills encadeadas por domínio), **18 agentes especializados**, **Memória Persistente Anti-Repetição** (`.agents/memoria/`), **Curadoria de Referências** (`references/`), **Checkpoint & Self-Healing Swarm Engine**, e uma **CLI executável (`izanagi`)** publicada no npm (`izanagi-ai`). Este repositório É o framework (não um app que o usa).
 
 ---
 
-## 2. Os 14 Agentes & Comandos Opencode (`/`)
+## 2. Os 18 Agentes & Comandos Opencode (`/`)
 
-O framework conta com **14 agentes especializados** em `agents/*.json` + orquestrador `/agents` (`.opencode/agent/agents.md`). Por padrão, tarefas complexas ativam o **Multi-Agent Swarm Mode** (execução paralela concorrente de múltiplos especialistas).
+O framework conta com **18 agentes especializados** em `agents/*.json` + orquestrador `/agents` (`.opencode/agent/agents.md`). Por padrão, tarefas complexas ativam o **Multi-Agent Swarm Mode** (execução paralela concorrente de múltiplos especialistas).
 
 | Comando | Arquivo | Papel & Especialidade |
 |---|---|---|
@@ -33,6 +33,10 @@ O framework conta com **14 agentes especializados** em `agents/*.json` + orquest
 | `/docs` | `agents/docs-agent.json` | Docs técnicos, READMEs, diagramas |
 | `/pm` | `agents/pm-agent.json` | Sprints, milestones, riscos |
 | `/professor` | `agents/professor-agent.json` | Ensino adaptativo, explicações |
+| `/researcher` | `agents/researcher-agent.json` | Investigação aprofundada, síntese de fontes |
+| `/evaluator` | `agents/evaluator-agent.json` | Critério técnico, avaliação objetiva de entregas |
+| `/adversarial-critic` | `agents/adversarial-critic-agent.json` | Crítica destrutiva-construtiva, pontos cegos |
+| `/form-engineer` | `agents/form-engineer-agent.json` | Formulários high-craft: validação, wizard, acessibilidade |
 
 ---
 
@@ -58,8 +62,8 @@ npm publish          # prepublishOnly roda build; depois: git push
 ## 4. Estrutura do Framework
 
 - `core/` — 10 engines (.md, incluindo `skill-composer.md` e `checkpoint-healing-engine.md`) + **`skill-resolver.json`** (mapa alias → target + seção `compositions`)
-- `agents/` — 13 definições de agentes em JSON (fonte da verdade para os comandos) com `chains` compostas
-- `skills/` — 207 skills em `skills/<name>/SKILL.md` (+ `references.md` opcional), incluindo `design-directions` (Style Selector por indústria), `ui-ux-pro-max` (design system com motor BM25 offline em Node) e `anti-ai-slop` (auditoria zero "cara de IA")
+- `agents/` — 18 definições de agentes em JSON (fonte da verdade para os comandos) com `chains` compostas
+- `skills/` — 212 skills em `skills/<name>/SKILL.md` (+ `references.md` opcional), incluindo `design-directions` (Style Selector por indústria), `ui-ux-pro-max` (design system com motor BM25 offline em Node) e `anti-ai-slop` (auditoria zero "cara de IA")
 - `references/` — curadoria de referências reais por domínio (webgl-3d, scrollytelling, ui-design-systems, stack-2026, performance-seo)
 - `.agents/memoria/` — memória persistente anti-repetição: `contexto.md`, `decisoes.md`, `erros-corrigidos.md`, `learnings.md`
 - `.opencode/agent/` — comandos slash do Opencode; adapters equivalentes gerados sob demanda em `.claude/`, `.codex/`, `.cursor/`, `.github/`, `.kimi/`

package/CHANGELOG.md

@@ -4,6 +4,47 @@
 
 ---
 
+## [2.10.0] — 2026-08-11
+
+### Added
+- **Agent Genome (PHASE 7)**: os 18 agentes core agora declaram os 13 campos formais do genome (purpose, capabilities, requiredSkills, optionalSkills, inputs, outputs, constraints, permissions, handoffs, memory, evaluation, tokenBudget, compatibility) — base para scoring e roteamento adaptativo.
+- **Agent Factory via CLI**: `izanagi agent create "<requisito>" [--name=slug] [--skills=a,b]` gera agentes com genome completo em `agents/generated/`, detecta lacuna vs. os 18 core (recusa lacuna já coberta) e é descoberto automaticamente por `loadAgent`/`agent list`.
+- **Skill Factory via CLI**: `izanagi skill create <nome> --gap="..." [--force]` cria skills em `skills/generated/<nome>/SKILL.md` com frontmatter de manifesto, security scan pré-escrita (persiste só com severidade LOW) e recusa de lacuna já coberta; bug de sobrescrita entre skills corrigido (subdir por skill + mkdir do parent).
+- **Tool Registry (MCP-ready)**: `src/runtime/tools/registry.ts` — tools builtin `fs.read`/`fs.write`/`fs.ls` com fluxo discover → permission → validate → execute, sandbox de zona (anti path-traversal) e permissões least-privilege.
+- **Evaluation Engine — veredito UNKNOWN**: sem métricas mensuradas o runtime agora emite **UNKNOWN** com recomendação explícita de evidência (antes: nunca retornava o veredito).
+- **Skill Scanner — DEFENSIVE_CONTEXT**: exemplos educativos/defensivos (não/evite/auditar...) deixaram de ser falsos positivos; `izanagi doctor --deep` passou a varrer as 212 skills sem falso positivo.
+- **Testes**: 14 novos (factories: 6, tools: 7, scanner defensivo) — total 136 testes de runtime passando.
+
+### Fixed
+- **DNG-001**: regex `\/\b` nunca casava comandos destrutivos → padrão corrigido.
+- **PER-001**: `Array.includes('*')` não detectava wildcards em permissões → `some(p => p.includes('*'))`.
+- **SkillFactory**: todas as skills eram gravadas no mesmo arquivo e `writeFileSync` falhava sem subdir → subdir por skill + `mkdirSync` do parent.
+- **Resolver/CLI**: `loadAgent` e `agent list` não enxergavam `agents/generated/` → agora varrem o diretório gerado.
+
+### Documentation
+- SYSTEM.md: novas seções (Execution Pipeline, Agent Factory & Skill Factory, Benchmarks & Regression, Model Router, Tool Registry, Doctor --deep) + tabela de módulos atualizada.
+- README.md: tabela de comandos da CLI reescrita (agent create, skill create --gap, workflow, eval, benchmark, trace, memory, doctor --deep).
+
+---
+## [2.9.6] — 2026-08-11
+
+### Fixed
+- **Healing Engine**: skill_replacement agora aplica de fato a substituicao de skill no no (reescreve node.skills com a skill de fallback) em vez de apenas registrar a intencao; validacao usa validateArtifact em PT-BR com healing por artefato invalido.
+- **Orchestrator**: avaliacao final consome o artefato test-results para reportar regressoes (testes falhando -> FAIL/BLOCKED com recomendacao); healing de validacao respeita retryNow com tentativas limitadas.
+- **Skill Scanner**: regras reais funcionando — DNG-001 (comando destrutivo), PER-001 (permissoes wildcard), SCR-001 (scripts no frontmatter), NET-001/002, SEC-001, INJ-001/003, DNG-002/003/004.
+- **LLM Executor**: adapters reais OpenAI/Anthropic/OpenRouter com validacao de env key, timeout e propagacao de erro HTTP (antes: stub inerte).
+- **Memory/Trace**: agent stats persistidos e traces JSONL com load/list/retry de escrita.
+- **Documentacao**: SYSTEM.md reescrito com a arquitetura real do runtime, AGENTS.md atualizado para 18 agentes / 212 skills / 15 composicoes, README.md reescrito.
+
+### Added
+- **122 testes de runtime** (node --test dist/runtime/tests/*.test.js): orchestrator (ciclo completo, retry, abort, skill_replacement, regressoes), evaluation, artifact contracts, resolver, scanner, memory, tracer, llm.
+- **Frontmatter de metadados** (name, description, version, compatibility, triggers, token_budget) em 27 skills que nao declaravam.
+
+### Enhanced
+- Composicoes do resolver mapeadas por categoria de runtime (implementation, testing, debugging, database_design).
+- .agents/memoria/ sincronizada com os aprendizados reais da sessao.
+
+---
 ## [2.8.0] — 2026-08-10
 
 ### Added

package/README.md

@@ -1,50 +1,20 @@
 # Izanagi AI
 
-Framework modular, skill-oriented para agentes de IA especializados em desenvolvimento de software e automação.
+Framework **meta** modular e skill-oriented para engenharia de software autônoma orientada a agentes: routing → orquestração → avaliação → healing → memória, com 18 agentes especializados, 212 skills e uma CLI executável publicada no npm (`izanagi-ai`).
 
-> **Filosofia:** Arquitetura primeiro. Código depois. Qualidade medida. Evolução contínua.
+> **Filosofia:** Arquitetura primeiro. Código depois. Qualidade medida. Evolução contínua. Zero "cara de IA".
 
 ---
 
 ## Instalação
 
-O Izanagi AI possui uma **CLI executável** que pode ser instalada globalmente ou usada via `npx`.
-
 ```bash
-# Instalação global
-npm install -g izanagi-ai
-
-# Ou execução direta via npx (sem instalar)
-npx izanagi <comando>
-
-# Agora use diretamente os comandos izanagi / izanagi-ai
+npm install -g izanagi-ai    # instalação global
+npx izanagi <comando>        # ou execução direta sem instalar
 izanagi --version
 ```
 
-> **Nota:** o pacote é publicado como `izanagi-ai` e os bins disponíveis são `izanagi` e `izanagi-ai`.
-
----
-
-## Iniciando um projeto
-
-```bash
-# Cria o projeto com seleção interativa de packs de skills (.agents/)
-izanagi init my-project
-
-# Ou especifique os packs diretamente (core é sempre incluído)
-izanagi init my-project --packs core,agents,coding,database
-
-# Entre no projeto e comece a usar
-cd my-project
-izanagi run "Create a login page"
-```
-
-O `init` cria:
-- `.agents/` — skills, agentes e engines selecionados
-- `.izanagi/izanagi.config.json` — configuração local do projeto
-- `opencode.json` — auto-carrega o framework quando o opencode abre o projeto
-
-**Packs disponíveis:** `core` (obrigatório), `agents`, `skills`, `architecture`, `coding`, `database`, `devops`, `security`, `testing`, `memory`, `optimization`, `teaching`.
+> O pacote é publicado como `izanagi-ai`; bins: `izanagi` e `izanagi-ai`.
 
 ---
 
@@ -53,67 +23,59 @@ O `init` cria:
 | Comando | Descrição |
 |---|---|
 | `izanagi init [dir] [--packs a,b,c]` | Cria projeto com `.agents/` e seleção de packs de skills. |
-| `izanagi run [agent] --task "<task>"` | Analisa a tarefa, seleciona o agente ideal e resolve a corrente de skills. |
-| `izanagi create <agent\|skill> <name>` | Cria scaffold de agente (JSON) ou skill (SKILL.md) no projeto atual. |
+| `izanagi run [agent] --task "<task>"` | Analisa a tarefa, seleciona o agente ideal e resolve a cadeia de skills (graph + eval + trace via `--runtime`). |
+| `izanagi agent create "<requisito>" [--name=slug] [--skills=a,b]` | Agent Factory: gera agente com genome completo em `agents/generated/` (detecta lacuna vs. 18 core). |
+| `izanagi agent list \| inspect <name>` | Lista/inspeta agentes (inclui `agents/generated/`) com genome. |
+| `izanagi skill create <nome> --gap="<descrição>" [--force]` | Skill Factory: cria skill com frontmatter, security scan pré-escrita e recusa de lacuna já coberta. |
+| `izanagi skill list \| search <q> \| inspect <name>` | Lista, busca e detalha skills. |
+| `izanagi create <agent\|skill> <name>` | Cria scaffold de agente (JSON) ou skill (SKILL.md). |
 | `izanagi compile <agente> [arquivo]` | Compila um System Prompt completo do agente + fundação do sistema. |
-| `izanagi list [skills\|agents]` | Lista todas as skills e agentes registrados com seus aliases. |
-| `izanagi doctor` | Valida integridade do framework, JSONs de agentes e mapeamentos de aliases. |
+| `izanagi workflow list \| inspect <template>` | Templates de grafo de execução por categoria (11). |
+| `izanagi eval <file.json> \| --metrics ... \| --report <run-id>` | Evaluation Engine: métricas ponderadas + veredito (PASS/.../UNKNOWN). |
+| `izanagi benchmark [compare]` | 10 benchmarks builtin + comparação de regressões entre builds. |
+| `izanagi trace [run-id]` | Traces de execução (spans, healing, graph, avaliação). |
+| `izanagi memory inspect \| search <q>` | Estado da memória de execução e busca em `.agents/memoria/`. |
+| `izanagi doctor [--deep]` | Auditoria de integridade; `--deep` adiciona security scan das 212 skills. |
+| `izanagi export --cli <cli>` | Regenera adapters multi-CLI (claude, codex, cursor, copilot, kimi, all). |
 | `izanagi --version` | Exibe a versão da CLI. |
 
 ### Exemplos
 
 ```bash
-# Task simples (auto-classificação)
-izanagi run "Create a login page"
-
-# Agente específico com task explícita
+izanagi run "Criar uma landing page de um SaaS de analytics"
 izanagi run architect --task "Design a microservices architecture"
-
-# Agente customizado criado no projeto
-izanagi create agent my-agent
-izanagi run my-agent --task "Create a login page"
-
-# Compilar system prompt completo para um agente
-izanagi compile architect prompt_arquiteto.md
-
-# Listar e validar
-izanagi list skills
-izanagi doctor
+izanagi agent create "Especialista em Laravel" --skills=php,api
+izanagi skill create rabbitmq-orchestrator --gap="Orquestração de mensageria RabbitMQ"
+izanagi workflow inspect fullstack
+izanagi eval --metrics correctness=0.9,security=0.8
+izanagi benchmark compare
+izanagi doctor --deep
 ```
 
 ---
 
-## Estrutura do Projeto
+## Estrutura do Repositório
 
 ```
 izanagi-ai/
-├── bin/            Executável da CLI (bin/izanagi.js)
-├── src/cli/        Código fonte dos comandos CLI
-├── core/           Motor central (decisão, contexto, reflexão, skill-resolver)
-├── agents/         Definições de Agentes de IA em JSON
-├── skills/         Skill base (111 skills especializadas em Markdown)
-├── memory/         Gerenciamento de memória e compressão
-├── optimization/   Redução de tokens e custos
-├── teaching/       Modo professor e aprendizado adaptativo
-├── architecture/   Padrões arquiteturais e design
-├── coding/         Skills de engenharia de software
-├── security/       OWASP, autenticação, auditoria
-├── testing/        Testes unitários, integração, E2E
-├── devops/         Docker, CI/CD, infraestrutura
-├── database/       SQL, NoSQL, otimização
-├── frontend/       Skills de frontend
-├── backend/        Skills de backend
-├── package.json    Configuração NPM para publicação CLI
-├── README.md       Documentação principal
-├── SYSTEM.md       Fundação do sistema
-└── RULES.md        Regras operacionais
+├── bin/             Executável da CLI (bin/izanagi.js → dist/cli)
+├── src/             Runtime real em TypeScript (orchestrator, evaluation, resolver, scanner, factories, tools, tracer, llm, cli)
+├── core/            Engines (.md) + skill-resolver.json (aliases → targets + compositions)
+├── agents/          18 definições de agentes em JSON (fonte da verdade dos comandos)
+├── skills/          212 skills em skills/<name>/SKILL.md (+ references.md opcional)
+├── references/      Curadoria de referências reais por domínio (webgl-3d, scrollytelling, stack-2026...)
+├── .agents/memoria/ Memória persistente anti-repetição (contexto, decisoes, erros-corrigidos, learnings)
+├── .opencode/       Comandos slash do Opencode (adapters em .claude/, .codex/, .cursor/...)
+├── AGENTS.md        Instruções de operação do framework
+├── SYSTEM.md        Fundação do sistema (arquitetura real do runtime)
+└── RULES.md         Regras operacionais (Anti-Generic High-Craft & Cinematic UI)
 ```
 
 ---
 
 ## Agentes e Skills
 
-O framework possui **111+ skills** e **10 agentes especializados** encadeados dinamicamente via `core/skill-resolver.json`.
+O framework possui **18 agentes especializados** (`/discovery`, `/architect`, `/senior-engineer`, `/techlead`, `/automation-engineer`, `/security`, `/devops`, `/database`, `/qa`, `/bug-hunter`, `/docs`, `/pm`, `/professor`, `/researcher`, `/evaluator`, `/adversarial-critic`, `/form-engineer`, `/animation`) e **212 skills** encadeadas por domínio via `compositions` do `core/skill-resolver.json` (248 aliases, 15 composições). Ver `AGENTS.md` para a tabela completa.
 
 ---
 
@@ -121,16 +83,19 @@ O framework possui **111+ skills** e **10 agentes especializados** encadeados di
 
 ```bash
 npm install       # instala dependências
-npm run build     # compila TypeScript → dist/
-npm run doctor    # roda o doctor localmente
-npm pack          # gera o tarball do pacote
+npm run build     # tsc && regenera .manifest
+npm run doctor    # auditoria de integridade
+node --test dist/runtime/tests/*.test.js   # 136 testes do runtime
+npm run verify    # build + teste de instalação em sandbox
 ```
 
+> **Gotcha:** `dist/` é gitignored e `bin/izanagi.js` importa de `../dist/cli/index.js` — rode `npm run build` antes de qualquer comando CLI local.
+
 ### Publicando no NPM
 
 ```bash
 npm run bump:patch   # ou bump:minor / bump:major
-npm publish --access public   # prepublishOnly roda o build automaticamente
+npm publish          # prepublishOnly roda o build automaticamente
 ```
 
 ---

package/SYSTEM.md

@@ -36,173 +36,179 @@ Every decision, every line of code, every interaction passes through a layered e
 ## Architecture Overview
 
 ```
-User Input
+User Input / Comando CLI
     │
     ▼
-┌─────────────────────┐
-│   Decision Engine   │ ← Classifies task, routes to skills
-└─────────┬───────────┘
-          │
-          ▼
-┌─────────────────────┐
-│   Context Engine    │ ← Builds context window, loads memory
-└─────────┬───────────┘
-          │
-          ▼
-┌─────────────────────┐
-│   Skill Executor    │ ← Activates skill chain (DAG)
-└─────────┬───────────┘
-          │
-          ▼
-┌─────────────────────┐
-│   Quality Gates     │ ← Validates output (security, style, etc.)
-└─────────┬───────────┘
-          │
-          ▼
-┌─────────────────────┐
-│   Reflection Engine │ ← Self-review, logs, evolution
-└─────────┬───────────┘
-          │
-          ▼
-┌─────────────────────┐
-│   Memory Manager    │ ← Compresses, stores, updates knowledge
-└─────────────────────┘
-          │
-          ▼
-       Output
+┌────────────────────────────┐
+│  Skill Resolver            │ ← aliases → paths, frontmatter, scoring,
+│  (core/skill-resolver.json)│   composições por domínio
+└─────────────┬──────────────┘
+              ▼
+┌────────────────────────────┐
+│  Orchestrator Runtime      │ ← template de grafo por categoria,
+│  (src/runtime/)            │   executeBatches, hooks de execução
+│                            │   (produce: agêntico / LLM / comando)
+└─────────────┬──────────────┘
+              ▼
+┌────────────────────────────┐
+│  Evaluation Engine         │ ← métricas ponderadas, veredito
+│  (artifacts + thresholds)  │   PASS / PASS_WITH_WARNINGS / FAIL / BLOCKED
+└─────────────┬──────────────┘
+              ▼
+┌────────────────────────────┐
+│  Healing & Learning        │ ← retry, skill_replacement, fallback,
+│  (checkpoint-healing)      │   abort; stats por agente + learnings
+└─────────────┬──────────────┘
+              ▼
+┌────────────────────────────┐
+│  Memory & Observability    │ ← MemoryStore (JSON), TraceStore (JSONL),
+│                            │   .agents/memoria/ persistente
+└─────────────┬──────────────┘
+              ▼
+           Output / Relatório
 ```
 
----
-
-## Core Modules
+## Core Modules (runtime real em `src/runtime/`)
 
 | Module | Responsibility |
 |--------|---------------|
-| **Decision Engine** | Classifies task type, priority, urgency. Selects skill chain. |
-| **Context Engine** | Builds minimal context window. Loads relevant memory. |
-| **Skill Executor** | Executes ordered skill chain with dependency resolution. |
-| **Token Manager** | Monitors token budget. Triggers compression when needed. |
-| **Memory Manager** | Short-term, long-term, project memory. Compression and recall. |
-| **Quality Gates** | Validates every output before delivery. |
-| **Reflection Engine** | Post-task self-review. Logs improvements. |
-| **Evolution Engine** | Updates skills based on reflection data. |
-
----
-
-## Decision Engine — Classification
+| **Orchestrator** (`orchestrator.ts`) | Executa grafos por categoria (implementation, debugging, testing, database_design, etc.), batches, retry e healing. |
+| **Evaluation Engine** (`evaluation/`) | Métricas ponderadas (correctness, completeness, security, etc.), veredito derivado, relatório com regressões e recomendações. |
+| **Artifact Contracts** (`contracts/artifacts.ts`) | 10+ schemas de artefato (requirements, architecture, database-schema, test-plan...) com validação por campos obrigatórios + tamanho mínimo, em PT-BR. |
+| **Skill Resolver** (`routing/resolver.ts`) | Alias → target (248), parse de frontmatter, scoring por relevância + histórico; `loadAgent` cobre `agents/` + `agents/generated/`. |
+| **Skill Scanner** (`security/skill-scanner.ts`) | 11 regras de segurança sobre skills (INJ, DNG, SCR, PER, NET, SEC) com severidade, allowlist e `DEFENSIVE_CONTEXT` (ignora exemplos defensivos/educativos). |
+| **Agent Genome** (`agents/*.json`) | 13 campos formais por agente (purpose, capabilities, requiredSkills, optionalSkills, inputs, outputs, constraints, permissions, handoffs, memory, evaluation, tokenBudget, compatibility) — preenchidos nos 18 agentes core. |
+| **Agent Factory** (`factories/agent-factory.ts`) | Gera novos agentes com genome a partir de requisito: detecção de lacuna vs. 18 core, ID slug, skills requeridas/opcionais, validação e escrita em `agents/generated/`. |
+| **Skill Factory** (`factories/skill-factory.ts`) | Cria skills novas com frontmatter, security scan pré-escrita, recusa de lacuna já coberta e escrita em `skills/generated/<name>/SKILL.md`. |
+| **Tool Registry** (`tools/registry.ts`) | Tools builtin (fs.read, fs.write, fs.ls) com sandbox de zona (anti path-traversal), permissões least-privilege e fluxo discover → permission → validate → execute. |
+| **Model Router** (`routing/model-router.ts`) | Seleção de modelo (claude/gpt/opus...) por custo/latência/contexto com fallback e override por env. |
+| **Healing Engine** | `retry` (transitório), `skill_replacement` (artefato inválido), `fallback`, `abort` (limite de tentativas). |
+| **Failure Memory** (`memory/store.ts`) | `recordFailure` + `findRelevantFailures` por categoria: erros reais registrados são injetados como evidência em runs futuros (anti-repetição). |
+| **Memory Store** (`memory/store.ts`) | Stats por agente, learnings, histórico de runs (JSON em disco). |
+| **Trace Store** (`observability/tracer.ts`) | Traces de execução em JSONL com spans, load/close e retry de escrita. |
+| **Benchmarks** (`benchmarks/`) | 10 casos builtin (parse, scoring, scanner, genome, composer...) executáveis via `izanagi benchmark` + `compare` entre builds. |
+| **LLM Executor** (`llm/`) | Adapters reais OpenAI/Anthropic/OpenRouter com env key, timeout e propagação de erro HTTP. |
+| **CLI** (`src/cli/`) | Entrypoint `bin/izanagi.js` → `runCLI` (doctor --deep, audit, resolve, export, init, agent create, skill create --gap, workflow, trace, eval, benchmark, memory, diagnose...). |
+
+## Routing — Classificação por Categoria
+
+O runtime mapeia a categoria da tarefa para um template de grafo + cadeia de skills (compositions em `core/skill-resolver.json`):
 
 ```
-if task == "new_project" or task == "new_feature":
-    chain = [Planning, Architecture, Requirements, Risks, Code]
-
-elif task == "bug":
-    chain = [Debug, RootCause, Fix, Test, Reflect]
-
-elif task == "refactor":
-    chain = [Architecture, Complexity, Refactor, Test, Validate]
-
-elif task == "review":
-    chain = [Reviewer, Security, Performance, Quality, Feedback]
-
-elif task == "question" or task == "explain":
-    chain = [Professor, Mentor, Examples, Exercises]
-
-elif task == "security_audit":
-    chain = [OWASP, Pentest, Auth, Secrets, Report]
-
-else:
-    chain = [Analyze, Plan, Execute, Review, Reflect]
+implementation → [requirements, architecture, schema, optimize, implementation-plan, evaluation]
+testing        → [test-plan, execution, critic, evaluation]
+debugging      → [reproduce, isolate, hypothesis, fix, verify, prevent, evaluation]
+database_design→ [requirements, schema, optimize, review, evaluation]
 ```
 
----
-
-## Token Budget Rules
+Categorias sem template específico usam o fluxo genérico (analisar → planejar → executar → avaliar). A cadeia completa de skills de cada domínio é definida pelas `compositions` do resolver.
 
-| Scope | Limit |
-|-------|-------|
-| Per-response (soft) | 2048 tokens |
-| Per-response (hard) | 4096 tokens |
-| Context window (max) | 8192 tokens |
-| Memory load per task | 1024 tokens |
-| Compression trigger | >70% of budget used |
+## Token Economy
 
-When budget is exceeded, `Compression Engine` activates automatically.
+Não há "compression engine" mágico: a economia de tokens é uma **skill operacional** (`skills/economia-tokens`) aplicada a toda sessão:
 
----
+- contexto mínimo: carregar só o que mudou; trechos/diffs em vez de arquivos completos;
+- prompt caching (conteúdo estático primeiro, dinâmico por último);
+- coordenação entre agentes por **artefatos em disco**, nunca payloads gigantes em contexto;
+- zero releituras. Economia vale para contexto inútil — nunca para o entregável.
 
 ## Quality Gates — Every Output
 
-All outputs **must** pass these gates before delivery:
+Todo output passa por gates reais antes de ser considerado entregue:
 
-1. ✅ **Security Gate** — No secrets, no injection vectors, no hardcoded credentials.
-2. ✅ **Style Gate** — Follows project conventions. Clean code.
-3. ✅ **Clarity Gate** — Output is understandable by the intended audience.
-4. ✅ **Conciseness Gate** — No fluff. Every sentence adds value.
-5. ✅ **Completeness Gate** — Answers the question. Does not leave loose ends.
-
----
+1. ✅ **Security Gate** — sem segredos no código; `skill-scanner` varre skills por injeção, comandos destrutivos, exfiltração e hardcode (11 regras), ignorando contexto defensivo/educativo.
+2. ✅ **Validation Gate** — artefatos validados contra schema (campos obrigatórios + tamanho mínimo); inválido → healing `skill_replacement`.
+3. ✅ **Evaluation Gate** — métricas ponderadas + veredito (PASS / PASS_WITH_WARNINGS / FAIL / BLOCKED / **UNKNOWN** quando faltam evidências mensuradas) com recomendações.
+4. ✅ **Style Gate** — segue `RULES.md`: anti-"cara de IA", design directions, high-craft.
+5. ✅ **Clarity & Conciseness Gate** — sem fluff; cada frase agrega valor.
+6. ✅ **Completeness Gate** — responde a pergunta, sem pontas soltas (Lei da Entrega Exaustiva).
 
 ## Memory Architecture
 
 ```
 ┌────────────────────────────────────────────┐
-│              Memory Manager                 │
-│                                            │
+│              Memory Store (runtime)         │
 │  ┌──────────┐  ┌──────────┐  ┌──────────┐ │
-│  │ Session  │  │ Project  │  │  Long    │ │
-│  │ Memory   │  │ Memory   │  │ Term     │ │
+│  │ Agent    │  │Learnings │  │  Runs/   │ │
+│  │ Stats    │  │ (erros   │  │  Trace   │ │
+│  │ (JSON)   │  │  evitados)│  │ (JSONL)  │ │
 │  └──────────┘  └──────────┘  └──────────┘ │
-│       │              │              │       │
-│       ▼              ▼              ▼       │
-│  ┌──────────────────────────────────────┐   │
-│  │         Knowledge Graph              │   │
-│  └──────────────────────────────────────┘   │
-│       │                                      │
-│       ▼                                      │
-│  ┌──────────────────────────────────────┐   │
-│  │         Recall Engine                │   │
-│  └──────────────────────────────────────┘   │
+│       └──────────────┬──────────────────┘ │
+│                      ▼                    │
+│        ┌─────────────────────────────┐    │
+│        │  .agents/memoria/ (projeto) │    │
+│        │  contexto · decisoes ·      │    │
+│        │  erros-corrigidos · learnings│    │
+│        └─────────────────────────────┘    │
 └────────────────────────────────────────────┘
 ```
 
----
+Memória entre sessões vive em `.agents/memoria/` (markdown curado). Memória de execução (stats, traces, learnings) vive no runtime (JSON/JSONL) — consulte `MemoryStore` e `TraceStore`.
 
 ## Evolution Cycle
 
 ```
-Task → Execute → Reflect → Log → Update Skills → Next Task
-                ↑                              │
-                └──────────────────────────────┘
-                         (feedback loop)
+Task → Executar → Avaliar (veredito) → Healing (corrigir) → Logar (stats/learning) → Próxima Task
+                ↑                                             │
+                └────────── (.agents/memoria/ atualizada) ─────┘
 ```
 
-Every task updates the skill base. The agent gets better over time.
+Melhoria contínua acontece por: healing registrado (retry/replacement/abort), stats por agente, learnings persistidos e atualização da memória curada do projeto.
 
----
+## Execution Pipeline (Runtime Adaptativo)
 
-## Versioning
+O ciclo completo de execução — `Task → Understanding → Planning → Execution Graph → Evaluation → Self-Healing → Reflection → Memory → Evolution` — é suportado por módulos reais:
 
-This framework uses **SemVer**. 
+1. **Understanding & Planning** — `requirements` decomposição de requisitos (artefatos em `contracts/artifacts.ts`), classificação da tarefa em categoria.
+2. **Execution Graph** — o Orchestrator monta um grafo por categoria (11 templates: implementation, testing, debugging, database_design...) com `parallelBatches` (nós independentes em paralelo, nós dependentes em sequência) e hooks de execução (`produce`: agêntico / LLM / comando).
+3. **Adaptive Routing** — o resolver pontua skills por relevância + histórico de uso por categoria (scorer com decaimento temporal), nunca lista estática; agents são resolvidos pelo mesmo scoring.
+4. **Evaluation** — métricas ponderadas (correctness, completeness, security, performance, requirementCoverage) com thresholds e veredito derivado; sem métricas mensuradas → **UNKNOWN** com recomendação explícita de evidência.
+5. **Self-Healing & Classification** — healing classificado (retry para transitório, `skill_replacement` para artefato inválido, fallback de modelo, abort por limite); cada healing é registrado com stats por agente.
+6. **Memory & Evolution** — `recordFailure` + `findRelevantFailures` (memória de falhas por categoria), learnings e traces; a memória curada `.agents/memoria/` é atualizada ao fim do ciclo.
 
-- **Major**: Breaking changes to skill interface or engine.
-- **Minor**: New skills, new modules, backward compatible.
-- **Patch**: Bug fixes, compression improvements, documentation.
+## Agent Factory & Skill Factory
 
-Current version: **2.0.0**
+Novos agentes e skills são **gerados, não escritos à mão**:
 
----
+- `izanagi agent create "<requisito>" [--name=slug] [--skills=a,b]` — o Agent Factory detecta lacuna vs. os 18 agentes core (recusa se o core já cobre), deriva ID slug, mapeia skills requeridas/opcionais, monta o genome completo (purpose, capabilities, inputs, outputs, handoffs, memory, evaluation, tokenBudget, compatibility), valida e escreve em `agents/generated/<id>.json` — descoberto automaticamente por `loadAgent`/`agent list`.
+- `izanagi skill create <nome> --gap="<descrição>" [--force]` — o Skill Factory recusa lacunas já cobertas, gera `skills/generated/<nome>/SKILL.md` com frontmatter de manifesto (name, description, version, compatibility, triggers, token_budget), roda o security scanner antes da escrita e só persiste com severidade LOW.
+
+## Benchmarks & Regression
+
+`izanagi benchmark` executa 10 casos builtin (resolver parse, scoring, skill scanner, genome, composer, artifact validation...); `izanagi benchmark compare` mede regressões entre builds (ex.: `2.9.6 → 2.10.0`) com delta por caso.
+
+## Model Router
+
+`src/runtime/routing/model-router.ts` seleciona o modelo por custo/latência/contexto (claude/gpt/opus...), com fallback em cadeia e override por env (`IZANAGI_MODEL`). O token budget de cada agente é declarado no genome e respeitado pelo runtime.
+
+## Tool Registry (Tools/MCP-ready)
+
+`src/runtime/tools/registry.ts` expõe tools builtin (`fs.read`, `fs.write`, `fs.ls`) atrás de um fluxo `discover → permission → validate → execute`: sandbox de zona (bloqueia path traversal via `..`), permissões least-privilege por tool, e schemas prontos para exposição a agentes externos (MCP-ready).
+
+## Doctor
+
+`izanagi doctor` audita integridade (SYSTEM.md/RULES.md, JSONs de agentes, aliases do resolver → targets); `izanagi doctor --deep` adiciona a varredura de segurança das 212 skills com `DEFENSIVE_CONTEXT` (exemplos educativos de segurança não são falsos positivos).
+
+## Versioning
+
+Versionamento **SemVer** gerenciado pelo npm (`npm run bump:patch|minor|major` + `npm publish`; versão atual no `package.json`).
+
+- **Major**: quebra de contrato de skills, agentes ou runtime.
+- **Minor**: novas skills, agentes, módulos — compatível com versões anteriores.
+- **Patch**: correções, otimização, documentação.
 
-## Compatibility
+## Frontmatter de Skills (Compatibility)
 
-All skills must declare:
+Skills com `SKILL.md` declararam (quando aplicável) metadados no frontmatter:
 
+- `name`
+- `description` (usado no scoring/resolução)
 - `version`
-- `dependencies` (list of required modules/skills)
-- `compatibility` (minimum SYSTEM version)
-- `triggers` (what activates this skill)
-- `token_budget` (estimated tokens per execution)
+- `compatibility` (versão mínima do framework)
+- `triggers`
+- `token_budget`
 
-Skills that do not declare these fields are rejected by the engine.
+O resolver **tolera** skills sem frontmatter (parse devolve `{}` e segue resolvendo pelo alias); metadados apenas aumentam a qualidade do scoring.
 
 ---