izanagi-ai 2.9.5 → 2.9.6

package/.manifest

@@ -1,11 +1,11 @@
 {
   "name": "izanagi-ai",
-  "version": "2.9.5",
+  "version": "2.9.6",
   "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-11T13:30:16.996Z",
   "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,25 @@
 
 ---
 
+## [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,49 @@ 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. |
+| `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 list [skills\|agents]` | Lista skills e agentes registrados com aliases. |
+| `izanagi doctor` | Auditoria de integridade: SYSTEM/RULES, JSONs de agentes, aliases → targets. |
+| `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 create skill meu-fluxo
 izanagi compile architect prompt_arquiteto.md
-
-# Listar e validar
 izanagi list skills
 izanagi doctor
 ```
 
 ---
 
-## 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, 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 +73,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   # 122 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,138 @@ 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. |
+| **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. |
+| **Skill Scanner** (`security/skill-scanner.ts`) | 11 regras de segurança sobre skills (INJ, DNG, SCR, PER, NET, SEC) com severidade e allowlist. |
+| **Healing Engine** | `retry` (transitório), `skill_replacement` (artefato inválido), `fallback`, `abort` (limite de tentativas). |
+| **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. |
+| **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, audit, resolve, export, init, run...). |
 
----
+## Routing — Classificação por Categoria
 
-## Decision Engine — Classification
+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).
+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) 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.
 
 ## Versioning
 
-This framework uses **SemVer**. 
-
-- **Major**: Breaking changes to skill interface or engine.
-- **Minor**: New skills, new modules, backward compatible.
-- **Patch**: Bug fixes, compression improvements, documentation.
+Versionamento **SemVer** gerenciado pelo npm (`npm run bump:patch|minor|major` + `npm publish`; versão atual no `package.json`).
 
-Current version: **2.0.0**
-
----
+- **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.
 
 ---
 

package/dist/cli/commands/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/run.ts"],"names":[],"mappings":"AAmDA,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CA2D7D;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAY9E;AAkBD,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAqKhE"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/run.ts"],"names":[],"mappings":"AAuDA,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CA2D7D;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAY9E;AAkBD,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CA6KhE"}