izanagi-ai 3.17.1 → 3.20.1

package/.manifest

@@ -1,11 +1,11 @@
 {
   "name": "izanagi-ai",
-  "version": "3.17.1",
+  "version": "3.20.1",
   "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:43:32.890Z",
+  "generatedAt": "2026-09-08T13:16:30.474Z",
   "agents": [
     {
       "id": "adversarial-critic",
@@ -541,7 +541,7 @@
         },
         {
           "id": "ai-slop",
-          "name": "Anti AI-Slop (Zero \"Cara de IA\")",
+          "name": "anti-ai-slop",
           "version": "1.0.0",
           "path": "skills/anti-ai-slop/SKILL.md"
         },
@@ -565,7 +565,7 @@
         },
         {
           "id": "architect",
-          "name": "Software Architect",
+          "name": "software-architect",
           "version": "1.0.0",
           "path": "skills/software-architect/SKILL.md"
         },
@@ -619,7 +619,7 @@
         },
         {
           "id": "billing",
-          "name": "Skill Payments & Billing — Izanagi",
+          "name": "payments-billing",
           "version": "1.0.0",
           "path": "skills/payments-billing/SKILL.md"
         },
@@ -703,7 +703,7 @@
         },
         {
           "id": "conversion-copywriting",
-          "name": "Skill Conversion Copywriting — Izanagi",
+          "name": "conversion-copywriting",
           "version": "1.0.0",
           "path": "skills/conversion-copywriting/SKILL.md"
         },
@@ -739,7 +739,7 @@
         },
         {
           "id": "deep-research",
-          "name": "Deep Research — Pesquisa Multi-Fonte com Síntese",
+          "name": "deep-research",
           "version": "1.0.0",
           "path": "skills/deep-research/SKILL.md"
         },
@@ -751,7 +751,7 @@
         },
         {
           "id": "design-directions",
-          "name": "Design Directions (Style Selector por Indústria)",
+          "name": "design-directions",
           "version": "1.0.0",
           "path": "skills/design-directions/SKILL.md"
         },
@@ -763,7 +763,7 @@
         },
         {
           "id": "design-system",
-          "name": "UI/UX Pro Max — Design Intelligence",
+          "name": "ui-ux-pro-max",
           "version": "1.0.0",
           "path": "skills/ui-ux-pro-max/SKILL.md"
         },
@@ -793,7 +793,7 @@
         },
         {
           "id": "editorial-layout",
-          "name": "Skill Editorial Layout — Izanagi",
+          "name": "editorial-layout",
           "version": "1.0.0",
           "path": "skills/editorial-layout/SKILL.md"
         },
@@ -817,7 +817,7 @@
         },
         {
           "id": "fan-out",
-          "name": "Parallel Agents (Fan-Out & Swarm Orchestration)",
+          "name": "parallel-agents",
           "version": "1.0.0",
           "path": "skills/parallel-agents/SKILL.md"
         },
@@ -835,13 +835,13 @@
         },
         {
           "id": "frontend",
-          "name": "Skill Frontend — Izanagi",
+          "name": "frontend",
           "version": "1.0.0",
           "path": "skills/frontend/SKILL.md"
         },
         {
           "id": "graphql",
-          "name": "Skill GraphQL — Izanagi",
+          "name": "graphql",
           "version": "1.0.0",
           "path": "skills/graphql/SKILL.md"
         },
@@ -871,7 +871,7 @@
         },
         {
           "id": "iac-terraform",
-          "name": "Skill IaC & Terraform — Izanagi",
+          "name": "iac-terraform",
           "version": "1.0.0",
           "path": "skills/iac-terraform/SKILL.md"
         },
@@ -883,7 +883,7 @@
         },
         {
           "id": "logging",
-          "name": "Logging Expert",
+          "name": "logging-expert",
           "version": "1.0.0",
           "path": "skills/logging-expert/SKILL.md"
         },
@@ -895,7 +895,7 @@
         },
         {
           "id": "memoria-projeto",
-          "name": "Memória do projeto",
+          "name": "memoria-projeto",
           "version": "1.0.0",
           "path": "skills/memoria-projeto/SKILL.md"
         },
@@ -919,7 +919,7 @@
         },
         {
           "id": "observability",
-          "name": "Observability Expert (Tracing Distribuído e Logs Estruturados)",
+          "name": "observability-expert",
           "version": "1.0.0",
           "path": "skills/observability-expert/SKILL.md"
         },
@@ -961,7 +961,7 @@
         },
         {
           "id": "qa",
-          "name": "Quality Assurance — Manual Operacional",
+          "name": "qa",
           "version": "1.0.0",
           "path": "skills/qa/SKILL.md"
         },
@@ -1015,7 +1015,7 @@
         },
         {
           "id": "security-privacy",
-          "name": "Security & Privacy — Manual Operacional",
+          "name": "security-privacy",
           "version": "1.0.0",
           "path": "skills/security-privacy/SKILL.md"
         },
@@ -1069,7 +1069,7 @@
         },
         {
           "id": "tdd",
-          "name": "TDD — Test-Driven Development (Iron Law)",
+          "name": "tdd",
           "version": "1.0.0",
           "path": "skills/tdd/SKILL.md"
         },
@@ -1129,7 +1129,7 @@
         },
         {
           "id": "web-perf-engineer",
-          "name": "Web Performance & SEO — Manual Operacional",
+          "name": "web-perf-seo",
           "version": "1.0.0",
           "path": "skills/web-perf-seo/SKILL.md"
         },

package/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md: Izanagi AI Framework Reference
 
-> Version 3.9.0
+> Version 3.20.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)
 
@@ -46,18 +46,18 @@ O framework conta com **22 agentes especializados** em `agents/*.json` + orquest
 
 ---
 
-## 3. Arquitetura Poliglota (Waves 1–4)
+## 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` (111 testes) · `cargo check -p izanagi_core --features wasm` |
+| `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)` (70 testes) |
+| `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) | smoke manual (`help`, `agent list`) — suíte própria pendente |
+| `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:**
@@ -73,7 +73,7 @@ Coexistência **Strangler Fig** (ADR-001): o legado npm (`src/`, CLI `izanagi`)
 # 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 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)
@@ -81,7 +81,7 @@ 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 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)
@@ -97,7 +97,7 @@ node packages/skill-migrator/cli.mjs --dry-run          # valida migração skil
 **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.
+- 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.
 
 ---
@@ -105,7 +105,7 @@ node packages/skill-migrator/cli.mjs --dry-run          # valida migração skil
 ## 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`)
+- `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)
@@ -117,7 +117,7 @@ node packages/skill-migrator/cli.mjs --dry-run          # valida migração skil
 **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/`)
+- `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)
 
@@ -163,7 +163,7 @@ O framework funciona em qualquer CLI de IA que leia `AGENTS.md` e possui adapter
 | **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).
+- `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.
 
 ---
 

package/CHANGELOG.md

@@ -4,6 +4,204 @@
 
 ---
 
+## [3.20.1]: 2026-09-08
+
+### Fixed
+- **`project.test` não executava nada no Windows, e a v3.20.0 foi publicada assim.** `spawn('npm.cmd', …, { shell: false })` sai `EINVAL`: desde o CVE-2024-27980 o Node recusa lançar `.cmd`/`.bat` sem shell. O `try/catch` do arquivo transformava o throw em `error` com `passed` ausente, o que é o comportamento correto para "não medi". O efeito, porém, era o item 1 da v3.20.0 (a métrica de teste vinda de um exit code) degradar para "não medi" em toda máquina Windows. Os dois testes de exit code de `project-test.test.ts` falhavam lá e passavam no Linux, e a Verificação da v3.20.0 afirmava "837, 837 passando" a partir de uma medição feita só no Linux, listando um único vermelho conhecido de Windows quando eram três.
+- **O conserto não custa a garantia do arquivo.** As duas saídas óbvias (`shell: true` e `cmd.exe /d /s /c`) recolocariam um interpretador de comandos no caminho, que é exatamente o que `shell: false` remove. A escolhida é outra: `resolveNpmCli()` acha o entrypoint JS do npm (ao lado do `node` no Windows, em `../lib/node_modules` em Unix) e o `spawn` passa a ser `process.execPath` com o npm como argumento de arquivo: sem shell, e com o binário mais confiável disponível, que é o mesmo node que executa o runtime. Se nenhum layout resolver, o chamador fica com o binário `npm` do PATH e o `EINVAL` volta a ser reportado como erro: "não medi" continua sendo ausência de `passed`, nunca reprovação.
+- **`TestRunner` ganhou `execFile`/`execArgs`, e o rótulo continua sendo o comando.** O que vai ao `spawn` e o que vai ao artefato deixaram de ser o mesmo par: `command`/`args` seguem `npm test --silent` nas duas plataformas, porque `node …/npm-cli.js test` diria COMO, não O QUÊ.
+
+### Verificação
+- **838 testes, 837 passando** (medido em 2026-09-08, no **Windows**). O único vermelho é `polyglot: bin Rust presente com --version barato`, anterior à rearquitetura: a fixture escreve um binário falso com shebang bash, e o Windows não honra shebang nem executa arquivo sem extensão conhecida. Continua aberto porque consertá-lo exigiria um condicional de plataforma, e o número deixaria de ser o mesmo nos dois sistemas.
+- O teste novo ("o que vai ao spawn nunca é um `.cmd`, e o rótulo continua sendo o comando") trava o motivo, não só o sintoma: afirma que o binário do `spawn` é `process.execPath` e que nenhum `.cmd` chega lá.
+
+### Compatibility
+- Nenhuma breaking change. `TestRunner.execFile` e `.execArgs` são opcionais, e `command`/`args` mantêm o valor de antes.
+
+---
+
+## [3.20.0]: 2026-09-05
+
+### Rodada de fechamento dos catorze itens abertos (2026-09-05)
+
+A auditoria de 2026-09-04 fechou doze tetos sem caller e deixou **catorze itens
+abertos**, cada um com critério de pronto escrito no `RUNTIME-PENDING.md`. Esta
+rodada fecha os catorze. O padrão que eles compartilhavam continua sendo o mesmo
+que o `HANDOFF.md` diz combater, agora numa segunda forma: não é o limite
+declarado que nada aplica, é a **evidência declarada que ninguém produz** —
+métrica de teste vinda de um texto que um agente escreveu, critério de aceite
+que fala da forma e nunca do pedido, memória que se escreve e não se lê, journal
+que se lê e não se consulta.
+
+### Added
+- **`project.test` e o check `exit-zero`: a métrica de teste passa a vir de um exit code.** A camada determinística tinha oito checks e nenhum executava nada; `testResults` vinha de um artefato `test-results` que um AGENTE escreveu, ou seja, do mesmo processo que deveria estar sendo testado. Com `--verify-tests`, o nó `verify-tests` roda o comando de teste do PROJETO no fim do grafo e `passed` é `exitCode === 0`, decidido pelo sistema operacional. **Isto não afrouxa o isolamento do `code.execute`:** a diferença é a fonte do comando. No `code.execute` o código vem do modelo, e por isso roda sem subprocesso, sem env herdado e sem rede confiável; aqui o comando vem do manifesto do projeto, o binário sai de uma allowlist fixa do runtime, o `spawn` é `shell: false` (sem expansão, sem `&&`, sem pipe) e nenhum campo de entrada carrega comando. Opt-in porque executa um processo do projeto com o ambiente herdado: a mesma confiança de digitar `npm test`.
+- **`--acceptance`: o critério do usuário passa a ser cobrado.** Todo critério era derivado do SCHEMA do artefato, então "adicionar paginação em GET /users" não produzia nenhum critério sobre paginação, e não existia flag, campo de SDK ou input para fornecer um. Prefixo conhecido (`contains:`, `not-contains:`, `matches:`, `min-size:`, `file-exists:`, `json-field:`, `references-exist`) vira check determinístico; prosa vira critério semântico, que precisa de juiz e sem juiz fica `UNVERIFIED`. O default é semântico de propósito: transformar uma frase em `contains` da frase inteira reprovaria toda entrega correta escrita com outras palavras, e um check inventado é pior que nenhum porque parece evidência.
+- **`--min-quality`: estratégias comparadas contra um piso.** Não existiam candidatos nem piso configurável (`minQuality`/`qualityFloor` tinham zero ocorrências no código), então "respeitando a qualidade mínima configurada" não tinha o que respeitar. Agora os modos até o sugerido viram candidatos, cada um estimado pelo mesmo caminho de roteamento da execução, e vence o mais barato que atinge o piso. Piso inalcançável **não sobe o modo em silêncio**: o plano segue no modo sugerido e declara que não cumpriu, porque subir seria o orçamento decidindo escopo.
+- **`--reuse-artifacts`: reuso de artefato entre runs.** `readContent` só era chamado por `izanagi explain`; um segundo run do mesmo objetivo refazia tudo. A parte que importa é a invalidação, e ela vem declarada antes do cache: a chave cobre tipo, objetivo, restrições, critérios, agente, papel, checksums dos insumos EM ORDEM e a impressão do projeto; run sem survey é chave DIFERENTE de run com survey; o prazo (7 dias) expira o que a chave não consegue ver. O artefato reaproveitado entra no lugar da CHAMADA e passa pela verificação inteira: o que se economiza é a chamada, não a prova.
+- **`--allow-tool` e `--verify-tests` na CLI.** A allowlist de tools existia no Orchestrator, no SDK e no caso de benchmark, e `izanagi run` não tinha flag para ela.
+- **`HUMAN_REQUIRED`: teto esgotado deixa de se confundir com falha por bug.** Cada abort por teto marca qual (`attempts`/`time`/`tokens`/`cost`) e o status do run muda. O veredito da AVALIAÇÃO continua `FAIL`, porque ela mede a entrega e a entrega não fechou: os dois campos convivem por medirem coisas diferentes. O exit code segue 1, não 2 — o 2 significa "retomável por `izanagi approve`", e um orçamento estourado não é.
+- **`ArtifactRegistry.lineage()` e `.compare()`.** As arestas de dependência estavam gravadas desde sempre e a leitura parava no primeiro vizinho; num grafo de sete nós, um salto nunca responde "de onde veio isto?". A travessia é em largura, com marca de visitado (ciclo termina em vez de girar), e `compare()` diz o que MUDOU entre versões, não só quanto o score caiu.
+- **`ArtifactRecord.checksum` (sha256 completo) e `.metadata` livre.** `hash` continua sha1 truncado em 12 hex porque é o que os registros gravados carregam: 48 bits bastam para "é o mesmo artefato de novo?", não para "este arquivo é exatamente o que eu gravei". `metadata` tem teto de 4KB e é recusado INTEIRO quando estoura.
+- **`EXTERNAL-TOOL-001`: tool registrada em runtime exige aprovação humana.** O default-allow da `PolicyEngine` permanece, com o motivo escrito (a `ToolRegistry` já nega o que o contrato não concedeu, a allowlist já nega o que não foi declarado, e se a política também fosse portão de concessão haveria três lugares decidindo a mesma coisa). O caso em que "não previsto" era perigoso ganhou regra própria. E `PolicyDecision.requiresApproval`, que existia e ninguém lia, virou pausa por `izanagi approve` em vez de falha que o healing retentaria contra uma porta fechada.
+- **`ExecutionEvidence.modelCalls` / `.agentCalls` / `.successRate` e `benchmark run --execute --compare`.** A comparação antigo vs novo cobria três dimensões e só sobre o PLANO. Chamadas contam por TENTATIVA, porque é o que a fatura conta, e nó reaproveitado não conta — é justamente a diferença que a comparação precisa enxergar.
+- **`triggers` e `capabilities` declarados nas 22 skills mais acionadas.** Das 106 skills, ZERO declaravam qualquer um dos dois: o haystack de `rankSkills` incluía dois arrays sempre vazios e o ranking escolhia entre 106 descrições soltas. Escritos à mão: derivar dos títulos de seção produziria "Identidade" e "Processo" como capacidade, e derivar da description colocaria as mesmas palavras duas vezes.
+- **`MemoryStore.appendKnowledge`.** A camada semântica era lida e nunca escrita pelo runtime: `.agents/memoria/semantica.md` só mudava quando uma pessoa o editava, e o que o runtime gravava (`addLearning`) vive numa lista plana que a busca não alcança.
+
+### Changed
+- **O Decision Journal deixa de ser write-only.** Cada decisão leva o objetivo do run; o fim do run carimba o veredito (`recordOutcome`, que não reescreve o que já foi carimbado); o planejamento consulta por semelhança de objetivo (`findRelevant`, só decisões com resultado conhecido). Um agente escolhido duas vezes para um objetivo semelhante, com os dois runs sem fechar e nenhum sucesso no meio, sai da disputa — e a troca vale também nos nós vindos do template do workflow. Duas falhas e não uma: um incidente pode ter sido provider fora do ar.
+- **`MemoryStore.search()` passa a ser consultado DURANTE o run.** Era chamado só pela CLI e pelo benchmark; dentro de um run, a única recuperação era padrão de falha. Agora o Context Resolver busca pelo objetivo de cada tarefa, com teto de 2 entradas e 600 chars, e um store por run. Numa rodada de correção o bloco fica de fora: o que falta ali é a correção, não mais contexto.
+- **`maxCost` vira limite do Healer.** `HealingInput` tinha tempo, tokens e tentativas; o custo só agia por `ExecutionBudget.spend`, ou seja DEPOIS de a chamada acontecer. Curar é decidir gastar mais uma chamada, e essa decisão passa a consultar o dinheiro antes.
+- **A nota de um caso de benchmark passa a incluir os validators.** Era só a razão de artefatos: um caso cujos arquivos apareceram e cujos validators reprovaram TODOS saía com `score: 1.00, passed: false`, e `compareBaselines` rankeia por `avgScore` — o baseline que acertou os nomes de arquivo e errou o conteúdo vencia o que acertou o conteúdo.
+
+### Fixed
+- **O total de tokens do trace saía 60% acima da telemetria do MESMO run.** `addTokens(result.tokens, result.tokens * 0.6)` soma os dois argumentos, e `result.tokens` é o total do provider (`input + output`), não a entrada. É o número que a CLI imprime, que `izanagi trace` mostra, que o dashboard exibe, que o webhook envia e que a Arena soma. Teste novo trava o invariante: trace e telemetria contam o mesmo run.
+- **Validators de um caso de benchmark liam o CAMINHO, não o arquivo.** Num output de diretório, `has-owasp` media se a palavra "owasp" estava no nome da pasta temporária: o validator passava ou reprovava por uma propriedade do diretório de trabalho.
+- **O registry de benchmark aceitava caso pela metade num `catch` vazio.** Um JSON sem `expectedArtifacts` chegava ao runner, estourava dentro do `try` da suíte, e o relatório culpava a execução por um defeito da definição. Caso recusado agora diz o motivo e o arquivo.
+- **Toda métrica declarada por um caso recebia a mesma razão de artefatos.** O relatório salvo mostrava `correctness`, `security` e `architecture` com o mesmo número: três medidas independentes que eram uma medida repetida três vezes. O que não é medido sai em `metricsNotMeasured`.
+- **A varredura anti-stub reprovava a evidência de uma suíte VERDE.** O runner de testes do Node imprime `ℹ todo 0` no resumo, e o artefato `test-run` de uma suíte 100% verde era reprovado por "stub detectado: TODO". A varredura pressupõe texto autoral; schema de saída capturada agora a desliga.
+- **`unmet` misturava reprovado com não-comprovado.** Um critério semântico sem juiz aparecia lado a lado com um check que de fato falhou, e quem lesse a linha (ou a restrição que o replanejamento deriva dali) trataria "não medi" como "está errado". Agora o não-comprovado vem marcado `[sem evidência]`.
+- **Dois objetos git vazios impediam o push.** `src/cli/commands/benchmark.ts` e `src/runtime/types.ts` tinham blobs truncados a zero byte no object store local, referenciados por oito dos nove commits da rodada. Reconstruídos byte a byte a partir dos blobs vizinhos legíveis, com o hash conferido antes de gravar: `git fsck` limpo, e nenhum commit reescrito.
+
+### Compatibility
+- Nenhuma breaking change. As quatro capacidades novas são **opt-in** (`--verify-tests`, `--acceptance`, `--min-quality`, `--reuse-artifacts`): sem elas, o plano, o grafo e o veredito são byte a byte os de antes, e há teste que mede isso.
+- `OrchestrationResult.status` e `IzanagiRunResult.status` ganharam o valor `HUMAN_REQUIRED`. Quem faz `switch` exaustivo sobre o status precisa tratá-lo; quem compara com `'PASS'` não muda. O exit code da CLI é o mesmo de antes.
+- `PlanEstimate.quality` é campo novo e obrigatório no tipo. Quem constrói um `PlanEstimate` à mão (fixtures de teste) precisa declará-lo; quem consome o que o `Commander.estimate` devolve não muda.
+- `ArtifactSchema.capturedOutput`, `ArtifactRecord.checksum`, `.metadata` e `.reuseKey` são opcionais: registro escrito por versão anterior continua legível.
+
+### Verificação
+- **837 testes, 837 passando** (medido em 2026-09-05, Linux). O vermelho conhecido de Windows (`polyglot: bin Rust presente com --version barato`) é anterior e independente. **Esta linha estava errada, e a 3.20.1 diz por quê:** no Windows eram três vermelhos, não um, e os dois extras eram justamente os de `project.test`.
+- `izanagi run "documentar a funcao de soma" --output docs --verify-tests --mode orchestrated` num projeto de fixture: suíte verde → `PASS`, 7/7 VERIFIED, `testResults=1`, score 1.00; suíte vermelha → `BLOCKED`, 6/7 VERIFIED, `testResults=0`, regressão nomeando `npm test --silent` com exit 1.
+- `izanagi run "..." --reuse-artifacts` duas vezes: run 1 gasta 900 tokens com cache 0/3; run 2 gasta **0 tokens** com cache 3/3, e continua `PASS` com 4/4 VERIFIED.
+- `izanagi run "..." --min-quality`: piso 0.4 escolhe `autonomous` ($0.0011, o único que atinge); piso 0.3 escolhe `assisted` ($0.0000, mesmo piso atingido por menos).
+- `izanagi benchmark run security --execute --compare`: tokens -300 (1500 → 1200), model calls -1 (5 → 4), agent calls -1 (3 → 2), latência +50ms, verificação n/a → 100%, sucesso 100% nos dois.
+
+---
+
+## [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