# Changelog

## [Unreleased] - feature/diagnostics-db

### Added
- 16 ferramentas de diagnóstico read-only/write para inspecção da base de dados Paperclip directamente via MCP, eliminando necessidade de psql nos skills `/clip-*`.
- Pool PostgreSQL singleton (`src/db.ts`) com export de `COMPANY_ID` e helper `query()` parametrizado.
- Variável de ambiente `PAPERCLIP_DB_URL` (default: `postgres://paperclip:paperclip@localhost:54329/paperclip`).
- Dependências `pg ^8.13.1` e `@types/pg ^8.11.10`.

### Diagnostic tools (read-only — 14)
1. `diag_agents_by_status` — contagem por status
2. `diag_agent_hierarchy` — árvore reports_to completa
3. `diag_agents_missing_permissions` — agentes sem entradas permissions
4. `diag_agents_missing_heartbeat` — agentes activos sem runs heartbeat
5. `diag_agents_without_membership` — agentes sem entrada activa em company_memberships
6. `diag_budget_orphans` — budget_policies/incidents a referenciar entidades inexistentes
7. `diag_routine_triggers_broken` — routine_triggers schedule sem next_run_at
8. `diag_heartbeat_token_usage(hours)` — token burn por agent últimas N horas
9. `diag_prompt_too_long_errors(hours)` — erros "prompt too long" últimas N horas
10. `diag_false_blockers` — issues blocked sem motivo real
11. `diag_stuck_routines(hours)` — routines presas há N horas
12. `diag_zombie_parents` — agentes com parent archived
13. `diag_company_skills_summary` — agregado company_skills por source_type
14. `diag_agent_full_context(agent_name)` — contexto completo de 1 agente (config + runs + membership + perms + tokens 24h)

### Diagnostic tools (write — 2)
15. `force_session_rotation` — rotação forçada de sessão (validação posterior)
16. `cancel_stuck_routine_issue` — cancelar issue de routine presa (validação posterior)

### Security
- 100% das queries SQL parametrizadas (`$1`, `$2`...). Zero string interpolation em SQL — verificado por grep.
- `npm audit`: 0 vulnerabilidades.

### Fixed
- `diag_agents_without_membership`: corrigido erro `operator does not exist: text = uuid` adicionando cast `a.id::text` e filtros `principal_type='agent' AND status='active'`.

### Migration
- 17 blocos psql substituídos por chamadas MCP em 5 skills `/clip-*`: clip, clip-agent, clip-health, clip-org, clip-routine. Skills clip-instructions/issue/skill mantêm psql (CRUD específico sem equivalente diag_*).

### Refs
- Desk CRM Task #2041
- Plano: `memory/mcp-paperclip-diagnostics-plan.md`