izanagi-ai 3.17.0 → 3.19.0

package/.manifest

@@ -1,11 +1,11 @@
 {
   "name": "izanagi-ai",
-  "version": "3.17.0",
+  "version": "3.19.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-09-02T13:41:16.345Z",
+  "generatedAt": "2026-09-04T12:48:45.274Z",
   "agents": [
     {
       "id": "adversarial-critic",

package/AGENTS.md

@@ -1,179 +1,179 @@
-# AGENTS.md: Izanagi AI Framework Reference
-
-> Version 3.9.0
-> Modular Skill-Oriented AI Prompt & Agent Framework for Autonomous Software Engineering
-> Multi-CLI: Opencode · Claude Code · Codex · Cursor · Copilot · Kimi (Smart Auto-Detection & Selective Generation)
-
----
-
-## 1. Visão Geral do Framework
-
-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 (catálogo v2 em `.skills/` convivendo com o legado `skills/`), **Skill Composer** (16 composições de skills encadeadas por domínio), **22 agentes especializados core + gerados**, **Memória Persistente Anti-Repetição** (`.agents/memoria/`), **Curadoria de Referências** (`references/`), **Checkpoint & Self-Healing Swarm Engine**, uma **CLI executável (`izanagi`)** publicada no npm (`izanagi-ai`) e uma **topologia poliglota** (Rust · Go · Python · TS — seção 3). Este repositório É o framework (não um app que o usa).
-
----
-
-## 2. Os 22 Agentes Especializados & Comandos Opencode (`/`)
-
-O framework conta com **22 agentes especializados** em `agents/*.json` + orquestrador `/agents` (`.opencode/agent/agents.md`). Tarefas complexas ativam o **Multi-Agent Swarm Mode** (execução paralela concorrente de múltiplos especialistas com isolamento de contexto).
-
-| Comando | Arquivo | Papel & Especialidade |
-|---|---|---|
-| `/agents` | `.opencode/agent/agents.md` | Orquestrador Multi-Agente (Swarm Mode padrão / Paralelo) |
-| `/discovery` | `agents/discovery-agent.json` | Pré-produção: entrevista condicional, pesquisa web, preview, prompt rico ⭐ |
-| `/product-reasoner` | `agents/product-reasoner-agent.json` | Entendimento: requisitos com evidências (FACT/ASSUMPTION/UNKNOWN), critérios BDD |
-| `/animation` | `agents/animation-agent.json` | Scrollytelling, 3D WebGL, motion signature |
-| `/architect` | `agents/architect-agent.json` | System design, Clean Arch, DDD, CQRS, ADRs |
-| `/senior-engineer` | `agents/senior-engineer-agent.json` | Full-stack dev, refactoring, código limpo/testável |
-| `/ai-engineer` | `agents/ai-engineer-agent.json` | Features com LLM: RAG, embeddings/vector DB, agentes com tool-calling/MCP, prompt engineering, avaliação/guardrails |
-| `/techlead` | `agents/techlead-agent.json` | Code review, governança, mentoria |
-| `/automation-engineer` | `agents/automation-engineer-agent.json` | Automação profissional: planilhas, browser, API, ETL |
-| `/security` | `agents/security-agent.json` | OWASP Top 10, auth, secure coding |
-| `/devops` | `agents/devops-agent.json` | CI/CD, Docker, K8s, IaC, observabilidade |
-| `/database` | `agents/database-agent.json` | SQL, PostgreSQL, Redis, modelagem de dados |
-| `/qa` | `agents/qa-agent.json` | QA & Test Automation: unitários, integração, E2E (Playwright), acessibilidade (WCAG) |
-| `/bug-hunter` | `agents/bug-hunter-agent.json` | Debug, root cause analysis |
-| `/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 |
-| `/agent-architect` | `agents/agent-architect-agent.json` | Projeta novos agentes (Genome, guardrails, avaliação) por lacuna real |
-| `/skill-architect` | `agents/skill-architect-agent.json` | Curadoria de skills: security scan, anti-duplicação, lacunas comprovadas |
-
-> **Histórico:** `agents/generated/` não é versionado — agentes gerados pela Agent Factory (`izanagi agent create`) ficam locais por padrão. O antigo exemplo `c-systems-engineer.json` foi removido na v2.13.0 e não deve mais ser listado como agente do framework.
-
----
-
-## 3. Arquitetura Poliglota (Waves 1–4)
-
-Coexistência **Strangler Fig** (ADR-001): o legado npm (`src/`, CLI `izanagi`) permanece intocado e publicável; o crescimento novo vive num SDK TypeScript + 4 núcleos nativos, orquestrados pela CLI de nova geração (`packages/cli`, binário `izanagi-next`). Referência canônica de contratos IPC, error codes (`-32001..-32005`), env vars e ADRs: **`docs/POLYGLOT.md`** (ADRs integrais em `.agents/memoria/decisoes.md`, gitignored).
-
-| Componente | Linguagem | Responsabilidade | Como testar |
-|---|---|---|---|
-| `crates/izanagi_core` | Rust | Quality engine: 7 heurísticas anti-slop sobre TS/Python/Go; protocolo NDJSON stdin/stdout (`validate`/`rules`/`version`) + op `scan-rationalizations` (`--file=<path>` / `--stdin`, exit 0/1/2); bindings WASM feature-gated (`--features wasm`, subcomandos `--version`/`--help`) | `cargo test --workspace` (111 testes) · `cargo check -p izanagi_core --features wasm` |
-| `crates/izanagi_mcp` | Rust | Cliente MCP JSON-RPC 2.0 sobre stdio: discovery + invocação pontual (`izanagi-mcp call --tool=<name>`) | incluso no `cargo test --workspace` |
-| `go-services/swarm_orchestrator` | Go | Orquestrador de swarm (Uber Fx): pipeline architect→engineer→qa→security via JSON-RPC 2.0 sobre UDS com event push | `(cd go-services/swarm_orchestrator && go build ./... && go vet ./... && go test ./...)` |
-| `python-engine/ast_analyzer` | Python ≥3.10 | Análise semântica multilíngue: símbolos, complexidade ciclomática, imports (tree-sitter + fallback estrutural) | `(cd python-engine && .venv/bin/python -m pytest tests/ -q)` (70 testes) |
-| `packages/sdk` | TypeScript | `@izanagi/sdk`: clientes tipados strict para os 4 núcleos + catálogo de skills; zero deps runtime | `(cd packages/sdk && npm install && npm test)` |
-| `packages/cli` | TypeScript | Binário `izanagi-next`: run em 4 fases com auto-heal (N=2), `agent list`, `skill list`, `gates check`; exit codes próprios (0 ok · 1 gate/falha · 2 uso · 3 ambiente) | smoke manual (`help`, `agent list`) — suíte própria pendente |
-| `packages/skill-migrator` · `agent-migrator` | Node ESM | Migradores determinísticos idempotentes: skills v1→v2 (106 módulos) e agents JSON→YAML (22) — ADR-004/005 | `node packages/agent-migrator/cli.mjs --check` · `node packages/skill-migrator/cli.mjs --dry-run` |
-
-**Gotchas poliglotas:**
-- Socket do orquestrador tem defaults divergentes por lado: servidor Go `/tmp/izanagi-orch.sock` (env `IZANAGI_ORCHESTRATOR_SOCK`) × SDK TS `/tmp/izanagi-swarm.sock` (env `IZANAGI_ORCHESTRATOR_SOCKET`). Case os dois via env antes de integrar (tabela completa em `docs/POLYGLOT.md`).
-- Testes do SDK/CLI NUNCA via strip-types direto sobre `.ts`: use o build próprio de cada pacote (`npm test` dentro de `packages/sdk`).
-- `Cargo.lock` é commitado (pins exatos, ex.: wasm-bindgen); build `.wasm` real só existe no job CI `wasm-build`.
-
----
-
-## 4. Comandos de Desenvolvimento (ordem importa)
-
-```
-# Legado npm (raiz)
-npm install          # instala deps
-npm run build        # tsc && node dist/scripts/generate-manifest.js
-npm test             # build + node --test dist/runtime/tests/*.test.js (284 testes)
-npm run verify       # build + teste de instalação em sandbox (passa todos os pack IDs)
-npm run doctor       # node bin/izanagi.js doctor [--deep]: auditoria de integridade
-npm run bump:patch   # npm version patch --no-git-tag-version (também minor/major)
-npm publish          # prepublishOnly roda build; depois: git push
-
-# Núcleos poliglotas
-cargo build --workspace                       # Rust: bins izanagi-core / izanagi-mcp em target/debug/
-cargo test --workspace                        # 111 testes (core + mcp)
-cargo check -p izanagi_core --features wasm   # type-check dos bindings WASM (ADR-003)
-(cd go-services/swarm_orchestrator && go build ./... && go vet ./... && go test ./...)
-(cd python-engine && .venv/bin/python -m pip install -r requirements-dev.txt && .venv/bin/python -m pytest tests/ -q)
-(cd packages/sdk && npm install && npm test)
-(cd packages/cli && npm install && npm run build)
-
-# Diagnóstico & catálogos v2
-node bin/izanagi.js polyglot status [--json|--strict]   # saúde dos 7 componentes poliglotas (--strict sai 1 se algo ausente)
-node packages/agent-migrator/cli.mjs --check            # drift YAML ↔ JSON (exit 0 sincronia / 1 drift / 2 uso)
-node packages/skill-migrator/cli.mjs --dry-run          # valida migração skills v2 sem escrever
-```
-
-**Gotchas críticos:**
-- `dist/` é gitignored e `bin/izanagi.js` importa de `../dist/cli/index.js`: **rode `npm run build` antes de qualquer comando CLI local** (`doctor`, `polyglot status`, `export`...), senão roda código obsoleto ou quebra. O mesmo vale para `packages/*/dist`: rode o build do package antes de consumir SDK/CLI-next.
-- `doctor`: instalação completa do usuário = `.agents/agents/` contendo agentes em **JSON** (formato distribuído); os YAMLs derivados do repo-fonte não caracterizam instalação.
-- Há test runner real (`node:test`, 284 testes em `src/runtime/tests/`). Verificação = `npm test` + `npm run verify` + `npm run doctor` + suítes poliglotas da seção 3.
-- Padrão de commit do repo: `chore: bump to vX.Y.Z` para bumps e `feat:`/`fix:`/`docs:` descritivos em PT-BR para mudanças.
-
----
-
-## 5. Estrutura do Framework
-
-**Legado (fonte canônica de agentes e skills):**
-- `core/`: 14 engines (.md, incluindo `skill-composer.md`, `checkpoint-healing-engine.md`, `quality-gates.md`) + **`skill-resolver.json`** (mapa alias → target, 258 aliases, 16 `compositions`)
-- `agents/`: 22 definições de agentes em JSON (fonte da verdade para os comandos) com `chains` compostas e Agent Genome (13 campos); derivados YAML em `.agents/agents/*.yaml` gerados pelo agent-migrator — proibido editar YAML à mão
-- `skills/`: legado histórico v1 (fonte do migrador). Catálogo ativo **v2**: `.skills/<name>/SKILL.md` (106 módulos; front-matter `name/description/version/category/tools.mcp` + seções Triggering Criteria / Step-by-Step Workflow / Verification Steps / Common Rationalizations / Red Flags; subpastas `references/`)
-- `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 (**gitignored**, só existe local): `contexto.md`, `decisoes.md` (ADRs), `erros-corrigidos.md`, `learnings.md`
-- `.opencode/agent/`: comandos slash do Opencode/Kimi CLI, gerados sob demanda a partir de `agents/*.json` (`izanagi export --cli opencode`), junto dos adapters de `.claude/`, `.codex/`, `.cursor/`, `.github/`, `.kimi/`
-- `src/`: CLI TypeScript (entrypoint: `src/cli/index.ts` → `runCLI`; multi-CLI export: `src/exporters.ts`; diagnóstico poliglota: `src/cli/commands/polyglot.ts`)
-- `SYSTEM.md` & `RULES.md`: fundação e regras operacionais (Anti-Generic High-Craft, Masterpiece Gate & Cinematic UI)
-
-**Poliglota (crescimento novo):**
-- `crates/`: workspace Rust na raiz — `izanagi_core` (quality engine + bindings WASM feature-gated), `izanagi_mcp` (cliente MCP stdio); `Cargo.lock` commitado
-- `go-services/swarm_orchestrator/`: orquestrador Go (Uber Fx, JSON-RPC 2.0 sobre UDS, event push, artefatos por estágio)
-- `python-engine/`: analisador AST multilíngue (tree-sitter + fallback, ~70 testes, venv em `.venv/`)
-- `packages/`: `sdk` (`@izanagi/sdk`), `cli` (binário `izanagi-next`), `skill-migrator`, `agent-migrator` — todos `private`
-- `docs/POLYGLOT.md`: referência canônica da topologia poliglota (contratos IPC, tabela de env vars, gaps conhecidos, resumo dos ADRs)
-
----
-
-## 6. Regras de Execução, Autonomia & Masterpiece Gate
-
-- **Estudo Antes de Codar (Study-First):** toda tarefa começa (1) carregando `.agents/memoria/contexto.md` (sempre) + só os arquivos de `.agents/memoria/` (`decisoes.md`, `erros-corrigidos.md`, `learnings.md`) do domínio da tarefa (cada agente nativo em `.claude/agents/*.md` já aponta pra sua fatia relevante, não é preciso reler os quatro por hábito), (2) consultando `references/` e/ou `deep-research` quando a tarefa exigir informação externa, e só então (3) arquitetar e implementar. Nunca programe no escuro, mas também nunca recarregue contexto irrelevante.
-- **Lei da Fidelidade Absoluta a Referências (Anti-Rush):** Quando solicitado clonagem, inspiração ou replicação de uma referência visual/técnica (ex: `igloo.inc`), os agentes têm **estritamente proibido** retornar respostas apressadas ou fingir estudo superficial. É obrigatório decompor rigorosamente a estrutura, tipografia, grid, animações e micro-interações da referência e entregar uma obra de excelência artesanal (*High-Craft*) idêntica ou superior.
-- **Zero Falsificação de Pesquisa (Anti-Fake-Research):** Nunca afirme ter estudado ou analisado um site ou documento sem processá-lo com profundidade real. Cada entrega reflete estudo genuíno e maestria técnica.
-- **Composição de Skills Obrigatória:** skills nunca são usadas isoladas. O `core/skill-composer.md` + `compositions` do `skill-resolver.json` definem cadeias encadeadas por domínio.
-- **Execução Paralela Concorrente:** Ative múltiplos agentes especializados simultaneamente para frentes distintas.
-- **Pré-instalação de Dependências:** Baixe e instale pacotes necessários (`npm install`) **antes** de criar ou alterar arquivos de código. Nunca espere o usuário fazer.
-- **Ponta a Ponta Autônomo & Lei de Entrega Completa de SaaS:** Execute tarefas até a conclusão total sem pausas desnecessárias. **Proibido atalhos ou landing-page-only:** quando o usuário solicitar um SaaS ou aplicação completa, a entrega deve obrigatoriamente incluir o ciclo vertical completo (Landing Page + Autenticação + Dashboard/Core App + Backend/Database + README).
-- **Lei da Entrega Exaustiva e Profunda (Anti-Stub / Anti-Lazy-Code):** Em QUALQUER solicitação (feature, componente, tela ou script), é **estritamente proibido** escrever código esparso, stubs vazios (`TODO`, `// implement later`) ou arquivos mínimos. Toda entrega deve ser **profunda, rica, robusta e completa de primeira**, com tipagem estrita, estados reais, tratamento de erros e lógica funcional pronta para produção.
-- **Lei da Geração de Código Real e Zero Listas (Anti-Checklist / Anti-Summary):** É estritamente proibido responder a pedidos de sistemas, apps ou SaaS com listas de tarefas resumidas (`[✓] 1. Criar banco...`), resumos textuais ou stubs vagos. O Izanagi exige a **geração de código real, completo e produtivo** para cada arquivo necessário (Schema Prisma, Rotas de API, Componentes React/Next.js com Tailwind, Middlewares de Auth, README de execução). Cada arquivo deve vir com seu código fonte 100% implementado, sem atalhos.
-- **Discovery Condicional:** Se o prompt do usuário já estiver detalhado e estruturado, o `/discovery` aprova automaticamente e gera o blueprint/prompt rico de imediato, sem entrevistas desnecessárias. Se for vago, conduz a entrevista sugerindo temas personalizados ao nicho.
-- **Style Selector Obrigatório (Design Directions First):** Em todo pedido de site/app/landing, apresente 3-5 direções de design BESPOKE para o nicho (`design-directions`): paleta exata, tipografia com personalidade, layout e motion signature: e o usuário escolhe antes de codar. Nunca template único.
-- **Anti AI-Slop (Zero "Cara de IA"):** toda UI entregue passa pela auditoria `anti-ai-slop` (ZERO tells: Inter default, gradientes roxo, hero + 3 cards, rounded-2xl uniforme, copy "Build the future"). Substituir por escolhas intencionais: tipografia distinta, cor dominante + acento, layout assimétrico, motion em 1-2 momentos-chave.
-- **Token Economy Ativa por Padrão:** a skill `economia-tokens` vale para toda sessão: contexto mínimo, prompt caching (estático primeiro, dinâmico por último), sliding window, coordenar agentes por artefatos em disco (nunca passar payloads gigantes entre agentes) e zero releituras. Economia se aplica a contexto inútil, nunca ao entregável.
-
----
-
-## 7. Padrão Anti-Generic / High-Craft & Cinematic UI
-
-Proibido entregar código/design genérico "cara de IA" (templates óbvios, fundos cinzas chapados, cards repetitivos, sem animação).
-- **Obrigatório:** Estética Apple-like / Awwwards-grade (`bg-zinc-950`, glassmorphism, bento grids, tipografia precisa, scrollytelling e micro-interações).
-- **Referências:** use `references/` como vocabulário técnico-visual: nunca invente URLs, nunca entregue colagem.
-
----
-
-## 8. Multi-CLI Compatibility & Smart Detection
-
-O framework funciona em qualquer CLI de IA que leia `AGENTS.md` e possui adapters gerados:
-
-| CLI | Arquivos | Comandos/Agentes |
-|---|---|---|
-| **Opencode** | `.opencode/agent/*.md` | `/discovery`, `/architect`, `/agents`... |
-| **Claude Code** | `CLAUDE.md` + `.claude/commands/*.md` + `.claude/skills/*/SKILL.md` | `/discovery`, `/architect`... via commands; skills nativas |
-| **Codex** | `AGENTS.md` + `.codex/instructions.md` + `.codex/agents/*.md` | agentes em markdown simples |
-| **Cursor** | `.cursor/rules/*.mdc` | rules globais (core/agents/memory) |
-| **GitHub Copilot** | `AGENTS.md` + `.github/copilot-instructions.md` | regras de codificação |
-| **Kimi CLI** | `kimi.md` + `.kimi/README.md` | compatível com convenção `.opencode/` |
-
-- `izanagi init` possui **detecção inteligente de CLI**: auto-detecta a CLI/IDE em uso (ou permite selecionar via `--cli opencode|cursor|claude|codex|copilot|kimi|all`), gerando **apenas** o adaptador necessário para manter o workspace limpo e sem poluição visual.
-- `izanagi export --cli opencode|claude|codex|cursor|copilot|kimi|all` regenera os adapters sob demanda (idempotente: nunca sobrescreve arquivos existentes).
-
----
-
-## 9. Release Flow & CI/CD (resumo)
-
-**CI — `.github/workflows/polyglot.yml`** (push/PR em `main`; jobs 100% paralelos, fail-fast global, actions fixadas por SHA): `legacy-npm` (build+test) · `rust` (clippy + test + check wasm) · `wasm-build` (`.wasm` E2E, ADR-003) · `go` (build/vet/test) · `python` (pytest com pins) · `ts-packages` (sdk test + cli build).
-
-**CD — `.github/workflows/publish.yml`**: exclusivo de tag `v*`/release; guard idempotente; least privilege. Pacotes poliglotas (`@izanagi/sdk`, `@izanagi/cli-next`) são `private` — só o legado npm publica (whitelist `files` não inclui `crates/`, `go-services/`, `python-engine/`, `packages/`, por decisão deliberada).
-
-1. `npm run bump:patch` (ou minor/major): bumpa `package.json`/`package-lock.json`
-2. `npm run build`: recompila + regenera `.manifest`
-3. Commit (`chore: bump to vX.Y.Z`) + `npm publish` (build roda via prepublishOnly)
-4. `git push`
+# AGENTS.md: Izanagi AI Framework Reference
+
+> Version 3.19.0
+> Modular Skill-Oriented AI Prompt & Agent Framework for Autonomous Software Engineering
+> Multi-CLI: Opencode · Claude Code · Codex · Cursor · Copilot · Kimi (Smart Auto-Detection & Selective Generation)
+
+---
+
+## 1. Visão Geral do Framework
+
+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 (catálogo v2 em `.skills/` convivendo com o legado `skills/`), **Skill Composer** (16 composições de skills encadeadas por domínio), **22 agentes especializados core + gerados**, **Memória Persistente Anti-Repetição** (`.agents/memoria/`), **Curadoria de Referências** (`references/`), **Checkpoint & Self-Healing Swarm Engine**, uma **CLI executável (`izanagi`)** publicada no npm (`izanagi-ai`) e uma **topologia poliglota** (Rust · Go · Python · TS — seção 3). Este repositório É o framework (não um app que o usa).
+
+---
+
+## 2. Os 22 Agentes Especializados & Comandos Opencode (`/`)
+
+O framework conta com **22 agentes especializados** em `agents/*.json` + orquestrador `/agents` (`.opencode/agent/agents.md`). Tarefas complexas ativam o **Multi-Agent Swarm Mode** (execução paralela concorrente de múltiplos especialistas com isolamento de contexto).
+
+| Comando | Arquivo | Papel & Especialidade |
+|---|---|---|
+| `/agents` | `.opencode/agent/agents.md` | Orquestrador Multi-Agente (Swarm Mode padrão / Paralelo) |
+| `/discovery` | `agents/discovery-agent.json` | Pré-produção: entrevista condicional, pesquisa web, preview, prompt rico ⭐ |
+| `/product-reasoner` | `agents/product-reasoner-agent.json` | Entendimento: requisitos com evidências (FACT/ASSUMPTION/UNKNOWN), critérios BDD |
+| `/animation` | `agents/animation-agent.json` | Scrollytelling, 3D WebGL, motion signature |
+| `/architect` | `agents/architect-agent.json` | System design, Clean Arch, DDD, CQRS, ADRs |
+| `/senior-engineer` | `agents/senior-engineer-agent.json` | Full-stack dev, refactoring, código limpo/testável |
+| `/ai-engineer` | `agents/ai-engineer-agent.json` | Features com LLM: RAG, embeddings/vector DB, agentes com tool-calling/MCP, prompt engineering, avaliação/guardrails |
+| `/techlead` | `agents/techlead-agent.json` | Code review, governança, mentoria |
+| `/automation-engineer` | `agents/automation-engineer-agent.json` | Automação profissional: planilhas, browser, API, ETL |
+| `/security` | `agents/security-agent.json` | OWASP Top 10, auth, secure coding |
+| `/devops` | `agents/devops-agent.json` | CI/CD, Docker, K8s, IaC, observabilidade |
+| `/database` | `agents/database-agent.json` | SQL, PostgreSQL, Redis, modelagem de dados |
+| `/qa` | `agents/qa-agent.json` | QA & Test Automation: unitários, integração, E2E (Playwright), acessibilidade (WCAG) |
+| `/bug-hunter` | `agents/bug-hunter-agent.json` | Debug, root cause analysis |
+| `/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 |
+| `/agent-architect` | `agents/agent-architect-agent.json` | Projeta novos agentes (Genome, guardrails, avaliação) por lacuna real |
+| `/skill-architect` | `agents/skill-architect-agent.json` | Curadoria de skills: security scan, anti-duplicação, lacunas comprovadas |
+
+> **Histórico:** `agents/generated/` não é versionado — agentes gerados pela Agent Factory (`izanagi agent create`) ficam locais por padrão. O antigo exemplo `c-systems-engineer.json` foi removido na v2.13.0 e não deve mais ser listado como agente do framework.
+
+---
+
+## 3. Arquitetura Poliglota
+
+Coexistência **Strangler Fig** (ADR-001): o legado npm (`src/`, CLI `izanagi`) permanece intocado e publicável; o crescimento novo vive num SDK TypeScript + 4 núcleos nativos, orquestrados pela CLI de nova geração (`packages/cli`, binário `izanagi-next`). Referência canônica de contratos IPC, error codes (`-32001..-32005`), env vars e ADRs: **`docs/POLYGLOT.md`** (ADRs integrais em `.agents/memoria/decisoes.md`, gitignored).
+
+| Componente | Linguagem | Responsabilidade | Como testar |
+|---|---|---|---|
+| `crates/izanagi_core` | Rust | Quality engine: 7 heurísticas anti-slop sobre TS/Python/Go; protocolo NDJSON stdin/stdout (`validate`/`rules`/`version`) + op `scan-rationalizations` (`--file=<path>` / `--stdin`, exit 0/1/2); bindings WASM feature-gated (`--features wasm`, subcomandos `--version`/`--help`) | `cargo test --workspace` (126 testes declarados no fonte) · `cargo check -p izanagi_core --features wasm` |
+| `crates/izanagi_mcp` | Rust | Cliente MCP JSON-RPC 2.0 sobre stdio: discovery + invocação pontual (`izanagi-mcp call --tool=<name>`) | incluso no `cargo test --workspace` |
+| `go-services/swarm_orchestrator` | Go | Orquestrador de swarm (Uber Fx): pipeline architect→engineer→qa→security via JSON-RPC 2.0 sobre UDS com event push | `(cd go-services/swarm_orchestrator && go build ./... && go vet ./... && go test ./...)` |
+| `python-engine/ast_analyzer` | Python ≥3.10 | Análise semântica multilíngue: símbolos, complexidade ciclomática, imports (tree-sitter + fallback estrutural) | `(cd python-engine && .venv/bin/python -m pytest tests/ -q)` (41 testes; o venv não é versionado) |
+| `packages/sdk` | TypeScript | `@izanagi/sdk`: clientes tipados strict para os 4 núcleos + catálogo de skills; zero deps runtime | `(cd packages/sdk && npm install && npm test)` |
+| `packages/cli` | TypeScript | Binário `izanagi-next`: run em 4 fases com auto-heal (N=2), `agent list`, `skill list`, `gates check`; exit codes próprios (0 ok · 1 gate/falha · 2 uso · 3 ambiente) | `npm test` dentro de `packages/cli` (13 testes em `tests/{run,skill}.test.ts`) |
+| `packages/skill-migrator` · `agent-migrator` | Node ESM | Migradores determinísticos idempotentes: skills v1→v2 (106 módulos) e agents JSON→YAML (22) — ADR-004/005 | `node packages/agent-migrator/cli.mjs --check` · `node packages/skill-migrator/cli.mjs --dry-run` |
+
+**Gotchas poliglotas:**
+- Socket do orquestrador tem defaults divergentes por lado: servidor Go `/tmp/izanagi-orch.sock` (env `IZANAGI_ORCHESTRATOR_SOCK`) × SDK TS `/tmp/izanagi-swarm.sock` (env `IZANAGI_ORCHESTRATOR_SOCKET`). Case os dois via env antes de integrar (tabela completa em `docs/POLYGLOT.md`).
+- Testes do SDK/CLI NUNCA via strip-types direto sobre `.ts`: use o build próprio de cada pacote (`npm test` dentro de `packages/sdk`).
+- `Cargo.lock` é commitado (pins exatos, ex.: wasm-bindgen); build `.wasm` real só existe no job CI `wasm-build`.
+
+---
+
+## 4. Comandos de Desenvolvimento (ordem importa)
+
+```
+# Legado npm (raiz)
+npm install          # instala deps
+npm run build        # tsc && node dist/scripts/generate-manifest.js
+npm test             # build + node --test dist/runtime/tests/*.test.js (764 testes)
+npm run verify       # build + teste de instalação em sandbox (passa todos os pack IDs)
+npm run doctor       # node bin/izanagi.js doctor [--deep]: auditoria de integridade
+npm run bump:patch   # npm version patch --no-git-tag-version (também minor/major)
+npm publish          # prepublishOnly roda build; depois: git push
+
+# Núcleos poliglotas
+cargo build --workspace                       # Rust: bins izanagi-core / izanagi-mcp em target/debug/
+cargo test --workspace                        # 126 testes declarados no fonte (core + mcp)
+cargo check -p izanagi_core --features wasm   # type-check dos bindings WASM (ADR-003)
+(cd go-services/swarm_orchestrator && go build ./... && go vet ./... && go test ./...)
+(cd python-engine && .venv/bin/python -m pip install -r requirements-dev.txt && .venv/bin/python -m pytest tests/ -q)
+(cd packages/sdk && npm install && npm test)
+(cd packages/cli && npm install && npm run build)
+
+# Diagnóstico & catálogos v2
+node bin/izanagi.js polyglot status [--json|--strict]   # saúde dos 7 componentes poliglotas (--strict sai 1 se algo ausente)
+node packages/agent-migrator/cli.mjs --check            # drift YAML ↔ JSON (exit 0 sincronia / 1 drift / 2 uso)
+node packages/skill-migrator/cli.mjs --dry-run          # valida migração skills v2 sem escrever
+```
+
+**Gotchas críticos:**
+- `dist/` é gitignored e `bin/izanagi.js` importa de `../dist/cli/index.js`: **rode `npm run build` antes de qualquer comando CLI local** (`doctor`, `polyglot status`, `export`...), senão roda código obsoleto ou quebra. O mesmo vale para `packages/*/dist`: rode o build do package antes de consumir SDK/CLI-next.
+- `doctor`: instalação completa do usuário = `.agents/agents/` contendo agentes em **JSON** (formato distribuído); os YAMLs derivados do repo-fonte não caracterizam instalação.
+- Há test runner real (`node:test`, 764 testes em `src/runtime/tests/`). Verificação = `npm test` + `npm run verify` + `npm run doctor` + suítes poliglotas da seção 3.
+- Padrão de commit do repo: `chore: bump to vX.Y.Z` para bumps e `feat:`/`fix:`/`docs:` descritivos em PT-BR para mudanças.
+
+---
+
+## 5. Estrutura do Framework
+
+**Legado (fonte canônica de agentes e skills):**
+- `core/`: 15 engines (.md, incluindo `skill-composer.md`, `checkpoint-healing-engine.md`, `quality-gates.md`) + **`skill-resolver.json`** (mapa alias → target, 258 aliases, 16 `compositions`)
+- `agents/`: 22 definições de agentes em JSON (fonte da verdade para os comandos) com `chains` compostas e Agent Genome (13 campos); derivados YAML em `.agents/agents/*.yaml` gerados pelo agent-migrator — proibido editar YAML à mão
+- `skills/`: legado histórico v1 (fonte do migrador). Catálogo ativo **v2**: `.skills/<name>/SKILL.md` (106 módulos; front-matter `name/description/version/category/tools.mcp` + seções Triggering Criteria / Step-by-Step Workflow / Verification Steps / Common Rationalizations / Red Flags; subpastas `references/`)
+- `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 (**gitignored**, só existe local): `contexto.md`, `decisoes.md` (ADRs), `erros-corrigidos.md`, `learnings.md`
+- `.opencode/agent/`: comandos slash do Opencode/Kimi CLI, gerados sob demanda a partir de `agents/*.json` (`izanagi export --cli opencode`), junto dos adapters de `.claude/`, `.codex/`, `.cursor/`, `.github/`, `.kimi/`
+- `src/`: CLI TypeScript (entrypoint: `src/cli/index.ts` → `runCLI`; multi-CLI export: `src/exporters.ts`; diagnóstico poliglota: `src/cli/commands/polyglot.ts`)
+- `SYSTEM.md` & `RULES.md`: fundação e regras operacionais (Anti-Generic High-Craft, Masterpiece Gate & Cinematic UI)
+
+**Poliglota (crescimento novo):**
+- `crates/`: workspace Rust na raiz — `izanagi_core` (quality engine + bindings WASM feature-gated), `izanagi_mcp` (cliente MCP stdio); `Cargo.lock` commitado
+- `go-services/swarm_orchestrator/`: orquestrador Go (Uber Fx, JSON-RPC 2.0 sobre UDS, event push, artefatos por estágio)
+- `python-engine/`: analisador AST multilíngue (tree-sitter + fallback, 41 testes; venv em `.venv/`, criado localmente e não versionado)
+- `packages/`: `sdk` (`@izanagi/sdk`), `cli` (binário `izanagi-next`), `skill-migrator`, `agent-migrator` — todos `private`
+- `docs/POLYGLOT.md`: referência canônica da topologia poliglota (contratos IPC, tabela de env vars, gaps conhecidos, resumo dos ADRs)
+
+---
+
+## 6. Regras de Execução, Autonomia & Masterpiece Gate
+
+- **Estudo Antes de Codar (Study-First):** toda tarefa começa (1) carregando `.agents/memoria/contexto.md` (sempre) + só os arquivos de `.agents/memoria/` (`decisoes.md`, `erros-corrigidos.md`, `learnings.md`) do domínio da tarefa (cada agente nativo em `.claude/agents/*.md` já aponta pra sua fatia relevante, não é preciso reler os quatro por hábito), (2) consultando `references/` e/ou `deep-research` quando a tarefa exigir informação externa, e só então (3) arquitetar e implementar. Nunca programe no escuro, mas também nunca recarregue contexto irrelevante.
+- **Lei da Fidelidade Absoluta a Referências (Anti-Rush):** Quando solicitado clonagem, inspiração ou replicação de uma referência visual/técnica (ex: `igloo.inc`), os agentes têm **estritamente proibido** retornar respostas apressadas ou fingir estudo superficial. É obrigatório decompor rigorosamente a estrutura, tipografia, grid, animações e micro-interações da referência e entregar uma obra de excelência artesanal (*High-Craft*) idêntica ou superior.
+- **Zero Falsificação de Pesquisa (Anti-Fake-Research):** Nunca afirme ter estudado ou analisado um site ou documento sem processá-lo com profundidade real. Cada entrega reflete estudo genuíno e maestria técnica.
+- **Composição de Skills Obrigatória:** skills nunca são usadas isoladas. O `core/skill-composer.md` + `compositions` do `skill-resolver.json` definem cadeias encadeadas por domínio.
+- **Execução Paralela Concorrente:** Ative múltiplos agentes especializados simultaneamente para frentes distintas.
+- **Pré-instalação de Dependências:** Baixe e instale pacotes necessários (`npm install`) **antes** de criar ou alterar arquivos de código. Nunca espere o usuário fazer.
+- **Ponta a Ponta Autônomo & Lei de Entrega Completa de SaaS:** Execute tarefas até a conclusão total sem pausas desnecessárias. **Proibido atalhos ou landing-page-only:** quando o usuário solicitar um SaaS ou aplicação completa, a entrega deve obrigatoriamente incluir o ciclo vertical completo (Landing Page + Autenticação + Dashboard/Core App + Backend/Database + README).
+- **Lei da Entrega Exaustiva e Profunda (Anti-Stub / Anti-Lazy-Code):** Em QUALQUER solicitação (feature, componente, tela ou script), é **estritamente proibido** escrever código esparso, stubs vazios (`TODO`, `// implement later`) ou arquivos mínimos. Toda entrega deve ser **profunda, rica, robusta e completa de primeira**, com tipagem estrita, estados reais, tratamento de erros e lógica funcional pronta para produção.
+- **Lei da Geração de Código Real e Zero Listas (Anti-Checklist / Anti-Summary):** É estritamente proibido responder a pedidos de sistemas, apps ou SaaS com listas de tarefas resumidas (`[✓] 1. Criar banco...`), resumos textuais ou stubs vagos. O Izanagi exige a **geração de código real, completo e produtivo** para cada arquivo necessário (Schema Prisma, Rotas de API, Componentes React/Next.js com Tailwind, Middlewares de Auth, README de execução). Cada arquivo deve vir com seu código fonte 100% implementado, sem atalhos.
+- **Discovery Condicional:** Se o prompt do usuário já estiver detalhado e estruturado, o `/discovery` aprova automaticamente e gera o blueprint/prompt rico de imediato, sem entrevistas desnecessárias. Se for vago, conduz a entrevista sugerindo temas personalizados ao nicho.
+- **Style Selector Obrigatório (Design Directions First):** Em todo pedido de site/app/landing, apresente 3-5 direções de design BESPOKE para o nicho (`design-directions`): paleta exata, tipografia com personalidade, layout e motion signature: e o usuário escolhe antes de codar. Nunca template único.
+- **Anti AI-Slop (Zero "Cara de IA"):** toda UI entregue passa pela auditoria `anti-ai-slop` (ZERO tells: Inter default, gradientes roxo, hero + 3 cards, rounded-2xl uniforme, copy "Build the future"). Substituir por escolhas intencionais: tipografia distinta, cor dominante + acento, layout assimétrico, motion em 1-2 momentos-chave.
+- **Token Economy Ativa por Padrão:** a skill `economia-tokens` vale para toda sessão: contexto mínimo, prompt caching (estático primeiro, dinâmico por último), sliding window, coordenar agentes por artefatos em disco (nunca passar payloads gigantes entre agentes) e zero releituras. Economia se aplica a contexto inútil, nunca ao entregável.
+
+---
+
+## 7. Padrão Anti-Generic / High-Craft & Cinematic UI
+
+Proibido entregar código/design genérico "cara de IA" (templates óbvios, fundos cinzas chapados, cards repetitivos, sem animação).
+- **Obrigatório:** Estética Apple-like / Awwwards-grade (`bg-zinc-950`, glassmorphism, bento grids, tipografia precisa, scrollytelling e micro-interações).
+- **Referências:** use `references/` como vocabulário técnico-visual: nunca invente URLs, nunca entregue colagem.
+
+---
+
+## 8. Multi-CLI Compatibility & Smart Detection
+
+O framework funciona em qualquer CLI de IA que leia `AGENTS.md` e possui adapters gerados:
+
+| CLI | Arquivos | Comandos/Agentes |
+|---|---|---|
+| **Opencode** | `.opencode/agent/*.md` | `/discovery`, `/architect`, `/agents`... |
+| **Claude Code** | `CLAUDE.md` + `.claude/commands/*.md` + `.claude/skills/*/SKILL.md` | `/discovery`, `/architect`... via commands; skills nativas |
+| **Codex** | `AGENTS.md` + `.codex/instructions.md` + `.codex/agents/*.md` | agentes em markdown simples |
+| **Cursor** | `.cursor/rules/*.mdc` | rules globais (core/agents/memory) |
+| **GitHub Copilot** | `AGENTS.md` + `.github/copilot-instructions.md` | regras de codificação |
+| **Kimi CLI** | `kimi.md` + `.kimi/README.md` | compatível com convenção `.opencode/` |
+
+- `izanagi init` possui **detecção inteligente de CLI**: auto-detecta a CLI/IDE em uso (ou permite selecionar via `--cli opencode|cursor|claude|codex|copilot|kimi|all`), gerando **apenas** o adaptador necessário para manter o workspace limpo e sem poluição visual.
+- `izanagi export --cli opencode|claude|codex|cursor|copilot|kimi|all` regenera os adapters sob demanda. **Idempotente com uma regra:** arquivo que carrega o `GENERATED_MARKER` é reescrito; arquivo sem o marker (ou seja, editado à mão) é preservado intocado. "Nunca sobrescreve arquivos existentes" era a leitura errada disso: quem editou o gerado sem tirar o marker perde a edição.
+
+---
+
+## 9. Release Flow & CI/CD (resumo)
+
+**CI — `.github/workflows/polyglot.yml`** (push/PR em `main`; jobs 100% paralelos, fail-fast global, actions fixadas por SHA): `legacy-npm` (build+test) · `rust` (clippy + test + check wasm) · `wasm-build` (`.wasm` E2E, ADR-003) · `go` (build/vet/test) · `python` (pytest com pins) · `ts-packages` (sdk test + cli build).
+
+**CD — `.github/workflows/publish.yml`**: exclusivo de tag `v*`/release; guard idempotente; least privilege. Pacotes poliglotas (`@izanagi/sdk`, `@izanagi/cli-next`) são `private` — só o legado npm publica (whitelist `files` não inclui `crates/`, `go-services/`, `python-engine/`, `packages/`, por decisão deliberada).
+
+1. `npm run bump:patch` (ou minor/major): bumpa `package.json`/`package-lock.json`
+2. `npm run build`: recompila + regenera `.manifest`
+3. Commit (`chore: bump to vX.Y.Z`) + `npm publish` (build roda via prepublishOnly)
+4. `git push`

package/CHANGELOG.md

@@ -4,6 +4,138 @@
 
 ---
 
+## [3.19.0]: 2026-09-04
+
+> **A 3.18.0 nunca chegou ao npm.** Ela foi para o GitHub e o `npm publish` não
+> aconteceu, então o registro parou na 3.17.1: esta release leva as duas rodadas
+> juntas. Mesma classe de incidente que a v3.4.0 (registrada na Fase 6 do
+> `ROADMAP.md`), e o motivo de existir o gate de banner de versão descrito
+> abaixo: "publicado" e "commitado" não são a mesma afirmação.
+
+### Rodada de auditoria do runtime contra a especificação (2026-09-04)
+
+Auditoria dos 49 itens de "Definition of Done" da especificação de evolução do runtime contra o código real, item por item. O `RUNTIME-PENDING.md` afirmava **nenhum item aberto**; a auditoria encontrou **doze tetos, campos e caminhos que existiam no código e não tinham caller**, mais um bug de formato entre produtor e consumidor do mesmo repositório. Nenhum deles é feature nova: são peças que o próprio runtime já declarava ter.
+
+O padrão é sempre o mesmo, e é o que o `HANDOFF.md` diz combater: **um limite declarado que nada aplica**.
+
+### Added
+- **Cancelamento cooperativo do run** (`OrchestratorOptions.signal`, `IzanagiRunOptions.signal`). O único `AbortSignal` do repositório era o timeout de `fetch` do cliente de modelo: não havia como parar um run, e o prazo por nó tirava o nó do caminho deixando a requisição em voo consumindo cota de um run que ninguém mais esperava. O sinal é conferido no topo de cada batch (o único ponto do laço onde parar não deixa trabalho pela metade), desce até a requisição por `CompletionOptions.signal` (combinado com o timeout HTTP via `AbortSignal.any`) e recusa a chamada antes de gastá-la quando já está abortado. **Ctrl-C na CLI cancela em vez de matar o processo**, e é a combinação com o checkpoint por batch que dá o valor: o progresso já pago fica em disco e `izanagi resume <run-id>` retoma dali. Um segundo Ctrl-C força a saída (exit 130). Run cancelado é `non-recoverable` no `Healer`: curar seria desobedecer quem cancelou.
+- **Prazo por nó aplicado de verdade** (`runtime/orchestration/deadline.ts`). `node.timeoutMs` é escrito por TODO o caminho de planejamento (templates do Planner, os quatro modos do Commander, os três nós de tool) e vira `TaskContract.budget.maxTimeMs`: nada no runtime lia nenhum dos dois. Um provider pendurado, ou uma tool externa registrada por `ToolRegistry.register`, travava o nó até o timeout HTTP do cliente de modelo; uma tool sem cliente HTTP travava indefinidamente. Vale o MENOR entre contrato e nó; ausência, zero e negativo significam "sem prazo", nunca "prazo zero". **A diferença entre prazo e cancelamento está declarada no arquivo:** prazo tira o nó do caminho do grafo e é retentável; cancelamento é do run inteiro, aborta a chamada em voo e não é retentável.
+- **`allowedTools`: allowlist de tools do run inteiro** (`OrchestratorOptions.allowedTools`, `IzanagiRunOptions.allowedTools`). Camada distinta da permissão do contrato: a permissão diz o que a TAREFA pode fazer, a allowlist diz o que este RUN pode usar, sem depender de nenhum contrato estar correto. Conferida ANTES da permissão e da política. Lista vazia é allowlist vazia (proíbe toda tool), ausência é "sem allowlist": a diferença é a forma de declarar "este run não usa tool".
+- **`BenchmarkCase.budget` / `.mode` / `.allowedTools`.** A base oficial de benchmark não tinha como declarar o teto sob o qual um caso deve ser resolvido: `benchmark run --execute` rodava todo caso sem orçamento, sem modo e sem restrição de tool. "Budget" e "allowed tools" eram observados no relatório e nunca impostos na execução, então um caso resolvido com dez vezes o orçamento passava igual.
+- **`task.verification.passed` / `task.verification.failed`: verificação por TAREFA.** `quality_gate.*` e `verification.completed` são do RUN (veredito final agregado, emitidos uma vez). Uma tarefa que reprovava a verificação não emitia evento nenhum, e o dado só aparecia em `result.verification` depois do await: quem observava o run em tempo real não tinha como saber que um nó reprovou. Aliases de SDK: `task:verification:failed` / `task:verification:passed`. Os antigos `verification:*` continuam apontando para o veredito do run, sem breaking change.
+- **`--max-concurrency N` em `izanagi run`.** O SDK sempre pôde declarar `budgetLimits.maxConcurrency`; a CLI não tinha por onde. Valor inválido é ignorado em vez de virar 0, porque 0 significa "sem teto" no pool: o oposto do que quem passa um número pediu.
+- **`ExecutionBudget.remainingTokens`.** Saldo do teto do run, nunca negativo. Existe para alimentar o roteamento por nó.
+- **`AgentCapability.modelHint` / `.declaredPermissions` / `.evaluation`.** Os 22 agentes core declaram `model`, `permissions` e `evaluation.metrics` em 22/22 arquivos, e o `parse()` do registry descartava os três. `declaredPermissions` tem esse nome porque a distinção é de segurança: é prosa do autor do agente (`"ler agents/"`), **não** o formato `fs:read`/`shell` que a `PolicyEngine` autoriza. Um agente não se autoriza declarando o que quer. `modelHint` é preferência, não id de catálogo: o modelo continua saindo do papel.
+- **`scripts/doc-version.ts` e o gate de banner de versão.** `bump.ts` e `release.ts` mexiam só no `package.json`, e nada conferia o resto: `ROADMAP`, `ARCHITECTURE`, `SYSTEM` e `RULES` diziam **3.10.0** e `AGENTS.md` **3.9.0** com o código em 3.18.0. Oito minors de drift, e a v3.6.0 já tinha corrigido isso à mão uma vez. O gate compara MAJOR.MINOR (patch é conserto, não mudança de arquitetura), `bump` imprime a lista do que revisar, e `release` **interrompe antes do publish** (`IZANAGI_ALLOW_DOC_DRIFT=1` libera). O banner NÃO é estampado automaticamente: escrever `3.19.0` num documento que ninguém leu é justamente afirmar um número que não aconteceu.
+
+### Fixed
+- **`recordRetry()` não tinha caller de produção.** Existia desde a v3.14.0, e por isso `telemetry.retries`, `RunTrace.retries` e o teto `budgetLimits.maxRetries` (plumbado do SDK e da CLI até o `ExecutionBudget`) eram estruturalmente mortos: `izanagi budget`, `izanagi trace` e o dashboard mostravam **0 retries** num run que tinha retentado três vezes, enquanto a Arena, contando por `node.attempts`, relatava o número certo. Duas contas do mesmo fato e só uma verdadeira. Agora conta no ponto da reexecução, ANTES de gastar a chamada, e `maxRetries` barra. Aprovação pendente não conta como retentativa (o ramo `pending` devolve a tentativa).
+- **`maxAgents` contava e não barrava.** O retorno booleano de `recordAgent` era descartado.
+- **Teto de run estourado era classificado como falha transitória e RETENTADO.** A mensagem do teto de tool calls contém a palavra "tool" e casava com a regra `/tool|mcp|exec|command failed|exit code/` do `Healer`, virando `kind: 'tool'`, que é recuperável: o runtime retentava um limite que não se move entre tentativas, gastando orçamento numa porta que continuaria fechada. Nova regra `non-recoverable` para teto excedido, posicionada antes da de `tool`.
+- **O Plano B do Commander era praticamente inalcançável.** `replan` só era acionado por falha de PLANEJAMENTO (mensagem casando `/plan|graph|cycle|topological/`). Reprovação da Verification Engine classifica como `validation` e ia direto para "troca a skill e tenta de novo", com o MESMO agente, MESMO papel e MESMA decomposição, até esgotar `maxAttempts`: o caminho de falha mais comum do runtime era exatamente o "repetir" que o replanejamento existe para evitar. Agora a 1ª falha de validação troca a skill (a correção mais barata primeiro) e a 2ª vai para o replan. Na prática alcança modo `autonomous`, que é onde há tentativa sobrando, e é onde o replanejamento deve viver.
+- **O `RoutingContext` era congelado no run inteiro.** Montado uma vez em `buildExecutionPlan` com `reasoningRequirement: 'medium'`, `risk: 0.2`, o `tokenBudget` do run e nenhum `historicalPerformance`, e reusado em todo nó. O `scoreModel` do `ModelRouter` lê todos esses campos: **metade dos critérios de roteamento estava implementada no scorer e nunca era alimentada**, e dentro de um run o modelo escolhido era função só do papel. `contextForNode` passa a derivar por tarefa: janela do teto da tarefa (limitada pelo saldo do run), risco da prioridade do contrato, raciocínio do papel, `requiresTools` do nó de tool e o histórico medido pela memória.
+- **`LOCAL_MAX_CONCURRENCY` era código morto.** A constante existia desde a v3.13.0 com o motivo escrito no arquivo ("GPU única não ganha nada com paralelismo") e zero referências no repositório: com `--local` o pool continuava em 3, disparando três requisições simultâneas contra a mesma GPU. Teto explícito do usuário vence, porque é ordem e não heurística.
+- **`parseFrontmatter` não lia lista de bloco YAML, e a `SkillFactory` só escreve lista de bloco.** Produtor e consumidor do mesmo repositório em formatos incompatíveis, com perda silenciosa: `triggers:` casava com o regex de chave e gravava string vazia, as linhas `  - valor` não casavam com nada, e `readSkill` derivava `[]`. Toda skill gerada pela Factory, e toda skill sintetizada por trajetória (que usa o mesmo escritor), perdia justamente o metadado pelo qual `rankSkills` a encontraria. Chave sem valor e sem itens segue string vazia, nunca `[]`: ausência de valor não é lista vazia. Chave aninhada (`tools:` para `mcp:`) continua fora de escopo, e declarado.
+- **`optional` decidia por id literal (`new Set(['critic'])`).** Um template de workflow do projeto do usuário com o nó de crítica sob outro nome, ou um agente gerado que produz `critique`, nunca era marcado como opcional: nem o early stopping nem o corte de opcionais por pressão de orçamento o alcançavam. A decisão passa a sair do QUE o nó produz. `evaluation` deliberadamente NÃO é reforço: pular o avaliador porque tudo passou seria pular quem afirma que passou.
+- **Um run cancelado tinha o checkpoint APAGADO.** `checkpoints.delete` roda em todo veredito terminal, com a premissa "não há mais o que retomar". Para cancelamento a premissa é falsa justamente aí: quem cancelou parou trabalho que ainda fazia sentido, e apagar o checkpoint tornava `izanagi resume` impossível no único caso em que ele é claramente o que se quer. Encontrado escrevendo o teste de cancelamento.
+- **Falha `non-recoverable` era RETENTADA quando casava com um padrão de falha da memória.** O passo de "padrão conhecido" do `Healer` vinha antes de a classificação decidir, e devolve `retryNow: true`: uma permissão negada gravada na memória era retentada, contra a regra que o próprio `KIND_RULES` declara na primeira linha. Valia desde antes desta rodada para permissão negada; passou a valer também para teto de run e cancelamento.
+- **Checkpoint era salvo só no fim da tentativa, não a cada batch.** O docstring de `captureCheckpoint` já dizia "chamado a cada rodada de batches" e não era verdade: um run interrompido no meio do grafo (Ctrl-C, crash, queda de rede) descartava todos os nós já concluídos daquela tentativa, e o `izanagi resume` recomeçava a tentativa inteira, pagando de novo chamadas de modelo já pagas. Persistido ao fim de cada batch, ANTES de decidir sobre a falha: o que terminou não se perde porque um irmão falhou.
+- **`VerificationEngine.isDone` não tinha caller, e o docstring dele contradizia o código.** Dizia "UNVERIFIED nunca é tratado como sucesso" enquanto o orquestrador marcava o nó `succeeded` e seguia. O nó CONTINUA seguindo, e isso é a decisão: sem juiz semântico (o default sem provider, e o de `--no-judge`) todo critério semântico fica sem evidência conclusiva, e derrubar o nó transformaria "não medi" em "está errado". O que faltava era o nó **carregar o fato**: `node.metadata.unverified` com status, motivo e critérios não comprovados, mais uma mensagem A2A de tipo `evidence`. Aprovado sem prova precisa ser distinguível de comprovado por quem lê o grafo.
+- **A lista literal de 19 agentes no `orchestrator.ts`.** Ela decide se a Agent Factory deve gerar um agente novo, e esquecia 3 dos 22 core (`ai-engineer`, `evaluator`, `form-engineer`) além de ignorar qualquer agente do projeto do usuário: o runtime podia sintetizar um agente para uma lacuna já coberta em disco. Passa pelo `AgentCapabilityRegistry`, com fallback para a lista antiga quando não há `agents/` legível. Este é o caminho legado, sem Commander, e projeto sem agentes em disco não deve deixar de rodar por isso.
+
+### Tests
+- **764 testes, 763 passando** (69 novos). O único vermelho segue sendo `polyglot: bin Rust presente com --version barato`, que escreve um binário falso com shebang bash: não roda no Windows, passa no Linux, e é anterior a esta rodada.
+- Novos arquivos: `cancellation.test.ts`, `deadline.test.ts`, `budget-ceilings.test.ts`, `frontmatter-block-list.test.ts`, `routing-per-node.test.ts`, `replan-reachability.test.ts`, `optional-reinforcement.test.ts`, `run-guarantees.test.ts`, `capability-fields.test.ts`, `doc-version-freshness.test.ts`.
+- Cada teto agora tem teste que MEDE o teto, não só a contagem: `maxRetries` barrando a reexecução, `maxAgents` barrando o agente, allowlist recusando a tool, prazo derrubando um producer que nunca resolve. Limite testado é um limite; limite só documentado é esperança.
+- `deadline.test.ts` fixa um limite que só aparece em produção: trabalho que **falha depois do prazo** não pode virar `unhandledRejection` e derrubar o processo. Um nó lento não é um crash do run.
+
+### Compatibility
+- **Nenhum breaking change de API.** `allowedTools`, `maxConcurrency`, `BenchmarkCase.budget`/`.mode`/`.allowedTools`, `remainingTokens`, `modelHint`, `declaredPermissions`, `evaluation` e os dois eventos novos são adições opcionais. `routeRole` ganhou um terceiro parâmetro opcional; os aliases `verification:*` do SDK continuam apontando para o veredito do run.
+- **Muda comportamento observável em quatro pontos, todos porque um teto passou a valer:** um run com `maxRetries`/`maxAgents` declarado agora falha o nó ao estourar (antes seguia); `--local` serializa o pool; um nó com `timeoutMs` declarado agora pode falhar por prazo; e uma 2ª falha de validação em modo `autonomous` replaneja em vez de retentar.
+- `release` passa a interromper antes do publish quando um banner de versão está desatualizado. `IZANAGI_ALLOW_DOC_DRIFT=1` publica com a drift registrada.
+
+---
+
+### Rodada anterior de auditoria de documentação
+
+Rodada de auditoria: três defeitos encontrados lendo o código contra a documentação, nenhum deles procurado. Todos da mesma família (o framework afirmando um número ou um caminho que ninguém conferiu), que é a família que o `HANDOFF.md` diz combater.
+
+### Added
+- **`ModelProvider.pricingAsOf`: a tabela de preços declara a própria data.** Preço em código-fonte apodrece sem avisar, e `estimateCostForRole` alimenta o teto de `ExecutionBudget`: preço velho é teto errado, e o teto é o que decide degradar, rebaixar papel ou pedir aprovação humana. `izanagi models` passa a mostrar a idade da tabela por provider e avisa acima de `STALE_CATALOG_AFTER_DAYS` (120 dias, escolha declarada e não medida). Provider self-hosted não declara data, porque custo 0 é fato e não cotação. Campo opcional no tipo: catálogo de projeto existente não quebra.
+- **`catalogAgeDays()` / `isCatalogStale()`** em `runtime/model/router.ts`. Sem data declarada a idade é `null`, nunca `0`: idade 0 afirmaria "o preço é de hoje", que é exatamente a afirmação impossível sem a data. Mesma regra de "ausência não é aprovação" já aplicada às métricas.
+- **`benchmarkReportsDir(stateDir)`** em `runtime/benchmarks/runner.ts`: fonte única do diretório de relatórios, usada pela escrita, pela leitura e pela mensagem que anuncia a escrita.
+- **`MemoryStore.stateFilePath` / `.memoryDirPath`**: onde o store de fato lê e grava, para que quem imprime o caminho imprima o mesmo que a escrita usou.
+
+### Fixed
+- **O catálogo default de modelos estava uma geração atrás, e isso não era cosmético.** `claude-opus-4-1` (premium), `claude-sonnet-4-5` (balanced) e `gpt-4.1` (premium, o default do papel `commander`) saíram do catálogo. Entraram, com fonte e data consultadas em 2026-09-03: `claude-opus-5` e `claude-sonnet-5`; `gpt-5.6-sol`; `gemini-3.8-flash` e `gemini-3.1-pro-preview`. Um id retirado da API faz a chamada falhar; um preço de geração anterior faz o teto de orçamento mentir. Dois cuidados registrados no código: `gpt-5.6-sol` entra com janela **272000** e não 1050000 (1M é opt-in experimental, e acima de 272K a entrada custa 2x e a saída 1.5x, então planejar contra 1M mentiria para cima), e `gemini-3.5-flash-lite` ficou **fora** apesar de ser mais barato, porque a janela de contexto dele não estava documentada na consulta: janela chutada num roteador que decide por contexto é pior que um modelo a menos.
+- **O caminho impresso do relatório de benchmark não era o caminho onde o relatório estava.** A escrita sempre foi para a raiz de estado (`<projeto>/.agents` num projeto inicializado); as três mensagens da CLI eram um literal `.izanagi/state/benchmarks/`, relativo ao `cwd`. Neste repositório esse diretório existe e guarda relatórios de agosto: caminho errado que parece certo é pior que caminho ausente, porque o número velho é lido como se fosse o novo. Agora a mensagem sai do mesmo cálculo da escrita. Mesma correção em `izanagi memory inspect`, que imprimia `.izanagi/state/runtime-state.json` sem raiz.
+- **`memoryCommand` e `dashboardCommand` recebiam `stateDir` num parâmetro chamado `baseDir`.** Funcionalmente corretos (a chamada em `cli/index.ts` sempre passou a raiz certa), mas é exatamente a confusão de raiz que já produziu dois bugs neste runtime. Renomeados.
+- **Documentação: `docs/HANDOFF.md` e `README.md` afirmavam 674 testes.** O medido era 682, e o `CHANGELOG.md` da mesma versão já dizia 682. Drift contra a regra do próprio `HANDOFF.md` ("só entra o que é verificável no código"). O `HANDOFF.md` também citava `.izanagi/state/benchmarks/` nos critérios de pronto, herdando o caminho errado da CLI.
+
+### Tests
+- 695 testes, 694 passando (13 novos: 5 em `benchmark-report-path.test.ts`, 8 em `model-catalog-freshness.test.ts`). O único vermelho segue sendo `polyglot: bin Rust presente com --version barato`, que não roda no Windows e é anterior a esta rodada.
+- **Dois testes existentes fixavam id de modelo no fonte e quebraram na atualização de catálogo** (`model.test.ts`, `model-role-routing.test.ts`). Reescritos para derivar o id do catálogo em tempo de teste: o que eles afirmam é o pin vencer a heurística e env vencer config, e nada disso tem a ver com id nenhum. Um id hardcoded ali volta a quebrar na próxima atualização, que é a lição do achado.
+- `model-catalog-freshness.test.ts` fixa duas invariantes que o conserto de valor sozinho não protege: nenhum id de geração retirada volta ao catálogo, e cada tier pago mantém a ordem de custo que `demoteRole` presume (se um preço novo invertesse a ordem, a degradação por orçamento passaria a AUMENTAR o gasto, em silêncio).
+
+### Compatibility
+- Nenhum breaking change de API. `pricingAsOf` é opcional. `benchmarkReportsDir`, `catalogAgeDays`, `isCatalogStale`, `STALE_CATALOG_AFTER_DAYS`, `MemoryStore.stateFilePath` e `.memoryDirPath` são adições. Os renames de parâmetro são posicionais e internos à CLI.
+- **Muda comportamento para quem não configura modelo:** o papel `commander` deixa de rotear para `gpt-4.1`. Quem dependia de um id específico deve fixá-lo em `.izanagi/izanagi.config.json` → `roles`, ou declarar o próprio catálogo em `models`.
+
+---
+
+## [3.18.0]: 2026-09-02
+
+O caminho seguro de tool existia desde a 3.15.0, era testado, e nenhum `izanagi run` passava por ele. Nesta versão o planejamento gera dois nós de tool em produção: um que **lê o projeto** antes de decidir, outro que **entrega arquivo** no fim.
+
+### Added
+- **`--output <dir>` / `output` no SDK — nó `deliver`.** Primeiro nó `kind: 'tool'` gerado pelo planejamento em produção. Grava o que o run produziu num documento único dentro do projeto, com contrato concedendo `fs:write` e mais nada. A verificação do nó confere o arquivo escrito: um critério `file-exists` sobre arquivo que ninguém escreveu passa quando o arquivo já existia por outro motivo; aqui ele passa a significar "o runtime gravou isto". O nome sai do objetivo, então repetir o mesmo objetivo reescreve a mesma entrega — entrega é produto, e o histórico continua em `.izanagi/state/`. `IzanagiRunResult.deliveredTo` só aparece quando a gravação realmente aconteceu.
+- **`project.survey` — nó `survey` na cabeça do grafo.** Levantamento determinístico do repositório: stack por manifesto e por volume de arquivo, manifestos resumidos, árvore por extensão, entrypoints e o começo do README. Não custa token; tem teto de profundidade (3) e de entradas, e **declara o próprio corte** (`truncated` é campo obrigatório do schema). Só as raízes do grafo dependem dele — repetir o levantamento em cada prompt seria a duplicação de contexto que a arquitetura proíbe. Ligado por default quando o diretório tem manifesto reconhecido; `--no-survey` desliga; modo `direct` nunca paga.
+- **Marcadores de input de tool** (`runtime/tools/input-refs.ts`): `{ $artifact: '<nó>' }` e `{ $deliverable: true }` resolvidos deterministicamente na hora da chamada, porque um nó de tool é declarado no plano antes de existir o que ele vai gravar. Referência a nó inexistente é erro, nunca string vazia. `code.execute` recusa marcador em qualquer campo do input: levar saída de modelo para dentro de código executado é injeção com outro nome.
+- **Kinds de artefato `delivery` e `project-survey`**, com schema próprio. `delivery` exige `written` (o comprovante da escrita, não o conteúdo); `project-survey` exige `root`, `stack`, `tree` e `truncated`.
+- **`OrchestratorOptions.workspaceDir`**: raiz do projeto do usuário, separada da raiz do framework.
+
+- **`project.materialize` — nó `materialize`, o código do agente vira arquivo.** O Blueprint Engine já definia o contrato de materialização (declare a árvore, escreva cada arquivo completo, zero stub) mas só em `--prompt-only`: um texto para a pessoa colar em outra ferramenta. Dentro do runtime o contrato não existia, e o código entregue ia para o content store como texto. Agora o contrato da tarefa PEDE o formato (`### FILE: <caminho>` + bloco de código) e um parser determinístico o materializa. **A fronteira que torna isto defensável**: os arquivos vão para um subdiretório da SAÍDA (`<output>/<slug do objetivo>/`), nunca por cima do código do projeto — o que o runtime produz fica num lugar que o usuário nomeou e pode revisar, apagar ou copiar. **Tudo ou nada**: a validação roda sobre o manifesto inteiro antes de qualquer escrita, porque "6 arquivos escritos, 3 recusados" é o relatório que engana. Recusa caminho absoluto, escape de diretório, caminho duplicado, arquivo vazio e arquivo com marca de trabalho não feito. Só entra no plano quando existe artefato que pode carregar código (`implementation`, `fixes`, `database-schema`, `api-contract`).
+- **Fundamentação medida e reportada em `izanagi run`**: dos caminhos que os artefatos citaram, quantos existem no projeto. É a única métrica que fala sobre o CONTEÚDO e não sobre a mecânica do runtime — verificação alta com fundamentação baixa é um run que cumpriu todos os critérios de schema descrevendo um projeto que não existe, e essa combinação é invisível em qualquer outra métrica. Conta REFERÊNCIAS e não artefatos (um plano que cita vinte caminhos e uma ADR que cita um não podem pesar igual). A Arena tem o campo e o agrega, mas **não o mede nos casos embutidos de propósito**: eles são tarefas sintéticas ("desenhe a arquitetura de um monólito modular para um SaaS de faturamento") que não falam do projeto onde o comando roda — um artefato correto para o caso citaria `src/modules/billing/` e sairia como não fundamentado em qualquer projeto real. O número existiria, pareceria significativo, e mediria a coisa errada; o relatório diz `n/a`. É o instrumento que a pergunta em aberto "o grounding melhora o resultado?" precisa para deixar de ser argumento e virar número.
+- **`produced` no payload de `--json` e do webhook**: o que o run gravou no projeto — o documento entregue e os arquivos materializados —, em caminhos RELATIVOS. É o que faltava para um agendador saber se há trabalho novo no disco sem abrir o trace. Caminho é metadado e cabe na regra do payload; caminho absoluto não cabe, porque carrega o diretório do usuário para um endpoint que costuma ser um canal de equipe. Ausente quando nada foi gravado, e ausência ali significa "não gravou", não "não sei".
+- **Teto total do documento entregue** (512KB). O teto por seção (128KB) sozinho não limitava nada: um run de nove nós produzia um documento de mais de um megabyte. Passado o teto, as seções seguintes entram como referência para `.izanagi/state/artifacts/` em vez de conteúdo — o leitor continua sabendo que o artefato existe e onde encontrá-lo inteiro.
+- **Outcome `not-applicable` na Verification Engine.** Distinto de `unknown`, e a diferença não é cosmética: `unknown` é "havia uma pergunta e a resposta não foi obtida" (juiz ausente) e NUNCA vira aprovação; `not-applicable` é "a pergunta não existe para este artefato". Groundedness sobre uma ADR que não cita arquivo nenhum não está sem resposta — está respondida por vacuidade. Sem essa distinção, o check novo derrubava todo artefato de prosa para `UNVERIFIED` e um `izanagi run` headless completo caía de `PASS` para `FAIL`. Critério inaplicável sai da conta: não conta como aprovado (não houve prova) nem como pendente (não há o que provar).
+- **Check determinístico `references-exist` (groundedness).** A Verification Engine perguntava se o artefato tem os campos do schema e o tamanho mínimo; não perguntava se o conteúdo corresponde a alguma realidade — e é por aí que a alucinação passava: um plano bem formatado, com todos os campos, citando `app/controllers/users_controller.rb` num projeto sem `app/`. O check extrai as referências de caminho e olha o disco. A pergunta NÃO é "todos os arquivos citados existem?" (um plano legítimo propõe arquivos novos, e reprovar isso viraria ruído contra o trabalho): é **"o LUGAR citado existe?"**. Cobrado só quando o run leu o projeto (`survey` ligado) — exigir um layout que nunca foi mostrado ao agente seria reprovar por informação que o runtime decidiu não dar. Artefato que não cita caminho nenhum fica `UNKNOWN`, nunca aprovado.
+
+### Fixed
+- **A telemetria de custo subestimava o gasto, e justamente na chamada que estourava o teto.** `ExecutionBudget.spend()` é chamado DEPOIS da resposta do modelo — os tokens já foram consumidos e o provider já cobrou —, mas recusava sem registrar quando o gasto passava de um teto. O run parava (certo), e reportava o consumo ATÉ a última chamada permitida (errado): num caso medido, `$0.001` de `$0.051` realmente gastos. Agora registra sempre e decide depois; parar continua sendo responsabilidade de quem chama, pelo `ok: false`. É a mesma classe do bug corrigido em `d1193ef` (resumo por fase divergindo da telemetria), num caminho que aquela correção não cobria.
+- **O resultado do gasto do juiz semântico era ignorado.** Com a fase `evaluation` esgotada, cada nó seguinte continuava chamando o juiz: o teto de avaliação era decorativo. Agora o juiz é desligado no primeiro gasto recusado, com span `budget:judge-off` no trace, e o critério semântico volta a `UNVERIFIED` — nunca aprovação por omissão. Reprovar o nó seria pior: o trabalho dele não tem culpa do orçamento de verificação ter acabado.
+- **O cache guardava resposta que reprovava na validação.** Na própria retentativa ela não voltava (a correção muda o system prompt, e portanto a chave), mas o run SEGUINTE com o mesmo objetivo recomeçava a partir da resposta que já se sabia ruim — deterministicamente, sempre. Um cache que existe para economizar não pode guardar o que já foi reprovado: o barato ali é repetir o erro. Agora só entra a resposta que produz artefato válido, conferida com a MESMA validação do Orchestrator (memoizada por `(kind, hash)`, então não paga segunda conta).
+- **O cache de resposta ficou no `baseDir` na separação de raízes.** Ele vive em `.izanagi/state/cache/responses` — é estado pelo mesmo critério de trace e memória —, e num projeto sem `izanagi init` as respostas de todo projeto continuavam se acumulando dentro da instalação do pacote.
+- **`izanagi diagnose` lia o `runtime-state.json` da instalação do framework**, então reportava "presente" olhando o estado de outro lugar.
+- **A telemetria afirmava paralelismo no momento em que ele era cortado.** `recordParallelBatch` recebia o tamanho do batch ANTES do teto de concorrência entrar, então um batch de 5 com pool de 1 aparecia como "paralelo 5" — e isso acontecia justamente no caso da degradação `reduce-parallelism`. Agora conta o paralelismo EFETIVO (`min(batch, pool)`).
+- **Decompor podia AUMENTAR o orçamento do pai.** O piso de 512 tokens por sub-tarefa existe para que uma sub-tarefa minúscula não gaste a chamada sem produzir nada — mas o piso sozinho quebrava a regra que ele servia: com 2000 tokens e 5 sub-tarefas, cada uma recebia 512 e o subgrafo saía com 2560. Decompor virava a forma de multiplicar o orçamento, que é exatamente o incentivo que "decompor não libera orçamento" existe para eliminar. Agora a LARGURA é limitada pelo que o pai paga no piso: quem não tem orçamento para duas sub-tarefas não decompõe, e um corte de largura é registrado em `issues` em vez de acontecer em silêncio.
+- **Sub-tarefa herdava as permissões do pai.** Hoje seriam inertes (só nó de tool as usa, e sub-tarefa não tem tool), mas conceder privilégio que ninguém vai usar é como um privilégio usado indevidamente começa. Menor privilégio é por construção, não por acidente de quem consome.
+- **A memória contava retentativa como recorrência.** O `Healer` registrava o padrão de falha conhecido a cada chamada de cura, e o orquestrador criava um `Healer` novo por rodada: um único incidente com três retries virava "3 ocorrências" e somava +0.09 de confiança. A memória passava a medir teimosia do runtime em vez de recorrência do problema — e é a recorrência que decide se um padrão vira conhecimento reutilizável e se o planejamento sobe o modo. Agora o `Healer` é do run e conta uma vez por `nó:padrão`: dentro do run é o mesmo incidente, entre runs é recorrência de verdade.
+- **`budgetLimits.maxTokens` era descartado em silêncio.** Custo, tempo, agentes, retries e tool calls do `budgetLimits` eram honrados; o teto de tokens era substituído pelo do plano sem erro nem aviso. Agora vale o MENOR dos dois: nenhum dos dois pode afrouxar o outro.
+- **Estado de projeto vazava para dentro da instalação do framework.** `resolveFrameworkRoot` responde "de onde leio agentes e skills?" e cai na instalação do pacote quando o projeto não tem `.agents/` — correto para assets. O estado (`.izanagi/state`: trace, artefatos **com conteúdo**, memória, checkpoints, decisões, aprovações) usava a mesma raiz, então todo projeto sem `izanagi init` gravava dentro de `node_modules/izanagi-ai/`, compartilhado com todos os outros. Consequências reais: `izanagi trace` listava execução de outro projeto, artefato de um projeto era legível de outro, e `npm update izanagi-ai` apagava o histórico. Novo `resolveStateRoot` e `OrchestratorOptions.stateDir` (default `baseDir`, então nenhum caller existente muda). **Projeto inicializado não muda de lugar** — mover o estado apagaria o histórico de quem já usa; o que muda é só o caso quebrado. Encontrado procurando o trace de um run de teste e achando 300 traces de outros projetos no diretório do framework.
+- **Sandbox de tool e `file-exists` resolviam contra a raiz do FRAMEWORK.** `baseDir` é `<projeto>/.agents` num projeto inicializado, ou a própria instalação do pacote quando não há uma. Um nó `fs.read` lia dentro de `.agents/` em vez do projeto, e um check `file-exists` procurava o arquivo no lugar errado. Rodando de dentro do checkout do framework as duas coincidem, que é exatamente por que passava despercebido.
+- **Nó que terminava `failed` sem produzir artefato era invisível para a avaliação final.** `correctness` é a média das verificações registradas e `artifactValidity` a razão dos artefatos existentes: as duas ignoram quem não chegou a produzir nada. Na prática, um nó abortado por permissão negada deixava o run terminar `PASS` com score alto. Agora cada nó falho entra como regressão — nó `optional` fica de fora, porque reforço que falha não invalida evidência que passou.
+- **Replanejamento apagava o contrato de um nó de tool.** `contractFor` por cima de um contrato de tool removeria `tool` e `permissions`, e o nó viraria uma chamada de modelo com o mesmo id: a "correção" seria uma regressão silenciosa. Nó de tool não tem plano B estrutural (não há agente para trocar nem papel para subir) e volta para a fila com o mesmo contrato, com o motivo registrado nas decisões.
+- **Duas fixtures de teste mediam a coisa errada.** `orchestrator.test.ts` e `checkpoint.test.ts` não cobriam o schema de `critique`/`test-plan`: o nó produzia artefato inválido, terminava `failed`, e o run seguia `PASS`. Só apareceu quando nó falho passou a contar.
+
+### Compatibility
+- **Nenhuma quebra.** Sem `--output` e sem `--survey`, o plano é byte-a-byte o de antes e nenhum nó do grafo recebe permissão. `workspaceDir` tem default `baseDir`, então todo caller existente do `Orchestrator` mantém o comportamento exato — a CLI e o SDK declaram o valor novo.
+- **Mudança de veredito possível**: um run cujo nó falhava sem produzir artefato passava a `PASS` e agora sai `FAIL`. Isso é a correção, não a regressão: o run reportava sucesso com uma tarefa não executada.
+
+### Tests
+- **Suíte de cenários ponta a ponta** (`e2e-scenarios.test.ts`): os dez cenários que a arquitetura precisa cobrir — trivial, médio, complexo, paralelo, falha, retentativa, escalada de papel, estouro de orçamento, parada antecipada e aprovação humana — cada um passando pelo Commander e pelo Orchestrator de verdade. Só o producer é injetado: substituir qualquer outra peça faria o teste medir a substituição em vez do runtime. Os outros arquivos testam peças; este testa comportamento observável de um run inteiro.
+- 682 testes, 682 passando (110 novos: 23 em `delivery.test.ts`, 18 em `grounding.test.ts`, 17 em `groundedness.test.ts`, 20 em `materialize.test.ts`, 10 em `e2e-scenarios.test.ts`, 5 em `state-root.test.ts`, 5 em `arena.test.ts`).
+
+---
+
+## [3.17.1]: 2026-09-02
+
+### Fixed
+- **`docs/` ficava fora do pacote npm.** O README publicado apontava para `docs/HANDOFF.md`, `docs/RUNTIME-PENDING.md` e `docs/POLYGLOT.md`, e quem instalava do registry encontrava links quebrados: a lista `files` do `package.json` nunca incluiu o diretório. Encontrado inspecionando o tarball publicado da 3.17.0.
+
+---
+
 ## [3.17.0]: 2026-09-02
 
 Decisão de produto que estava pendente desde a Fase 4, tomada: **o Izanagi é local-first**. Não fica de pé, não escuta porta, não guarda credencial em repouso. Quem agenda é o cron ou o Task Scheduler do sistema, e esta versão entrega o que faltava para eles conseguirem consumi-lo.