# Architecture Decision Records

Decisões de arquitetura do AgentPack, uma por arquivo, no formato contexto → decisão → consequências.
Número novo = o próximo livre; um ADR aceito não é reescrito, é substituído por outro que o cite.

Os ADR-001 a ADR-009 vêm do plano NEW-001 do Knowledge e são citados no código (`ADR-00N` nos
comentários), mas o documento original se perdeu. Foram reconstruídos a partir do código em
2026-09-25 e dizem isso no status.

| ADR | Título | Status |
| --- | --- | --- |
| [ADR-001](0001-knowledge-versoes-append-only.md) | Knowledge com hierarquia, escopo e versões append-only | Reconstruído |
| [ADR-002](0002-knowledge-cache.md) | Cache de knowledge em três camadas, Redis com fallback em memória | Reconstruído |
| [ADR-003](0003-knowledge-hierarquia.md) | Hierarquia de knowledge por parent_id com caminho ltree | Reconstruído |
| [ADR-004](0004-knowledge-sanitizacao.md) | HTML de knowledge saneado no servidor, sem script | Reconstruído |
| [ADR-005](0005-busca-postgres-first.md) | Busca Postgres-first (FTS + pg_trgm) | Reconstruído |
| [ADR-006](0006-knowledge-service-unico.md) | Um service único para o Knowledge | Reconstruído |
| [ADR-007](0007-knowledge-vinculo-task.md) | Knowledge vinculado a tasks (escopo demand) | Reconstruído |
| [ADR-008](0008-migracao-knowledge-legado.md) | Migração do knowledge legado | Reconstruído |
| [ADR-009](0009-knowledge-formato-de-saida.md) | Normalizador único do formato de knowledge na saída | Reconstruído |
| [ADR-010](0010-deny-by-default.md) | Autenticação deny-by-default em /api e /mcp | Aceito |
| [ADR-011](0011-mcp-stateless.md) | Gateway /mcp stateless com toolsets | Aceito |
| [ADR-012](0012-erros-e-contrato-zod.md) | Contrato em zod e erros RFC 9457 | Aceito |
| [ADR-013](0013-schema-so-por-migration.md) | Schema do banco só por migrations versionadas | Aceito |
| [ADR-014](0014-render-design-system-versioning.md) | Design system global com publicação versionada e upgrade por decisão humana | Aceito |
| [ADR-015](0015-mcp-sessao-por-conversa.md) | Sessão de destino MCP por conversa, gateway continua stateless | Aceito |
| [ADR-016](0016-mcp-envelope-unico-e-versao-por-tool.md) | Envelope único na resposta de tool e versão por tool | Aceito |