descomplicar-meta-plugin/commands/db-cleanup.md

---
name: db-cleanup
description: >
  Limpeza de órfãos nas tabelas de relacionamento cr_*.
  Remove referências inválidas com backup automático.
argument-hint: "[--table=X] [--dry-run] [--no-backup]"
---

# /descomplicar:db-cleanup

Detecta e remove registos órfãos nas tabelas de relacionamento da infraestrutura Claude Code.

## Objectivo

Garantir integridade referencial das tabelas cr_* removendo registos que apontam para entidades inexistentes (órfãos).

## Sintaxe

```
/descomplicar:db-cleanup [options]
```

| Opção | Descrição | Default |
|-------|-----------|---------|
| `--table=X` | Limpar apenas tabela específica | todas |
| `--dry-run` | Mostrar o que seria removido sem executar | false |
| `--no-backup` | Não criar backup (não recomendado) | false |
| `--force` | Não pedir confirmação | false |

## Output Esperado

```
╔════════════════════════════════════════════════════════════╗
║  DB CLEANUP                                                ║
╠════════════════════════════════════════════════════════════╣
║  Backup criado: cr_orphans_backup_20260204                 ║
║  cr_agent_mcps:    12 → 0 órfãos   ✓                       ║
║  cr_agent_skills:   3 → 0 órfãos   ✓                       ║
║  cr_skill_mcps:     5 → 0 órfãos   ✓                       ║
╠════════════════════════════════════════════════════════════╣
║  TOTAL REMOVIDO: 20 órfãos | Integridade: ✓ OK             ║
╚════════════════════════════════════════════════════════════╝
```

## Tabelas Verificadas

| Opção | Descrição | Default |
|-------|-----------|---------|
| `--table=X` | Limpar apenas tabela específica | todas |
| `--dry-run` | Mostrar o que seria removido sem executar | false |
| `--no-backup` | Não criar backup (não recomendado) | false |
| `--force` | Não pedir confirmação | false |

## Tabelas Verificadas

| Tabela | FK 1 | FK 2 |
|--------|------|------|
| `cr_agent_mcps` | agent_id → cr_agents | mcp_id → cr_mcps |
| `cr_agent_lsps` | agent_id → cr_agents | lsp_id → cr_lsps |
| `cr_agent_skills` | agent_id → cr_agents | skill_id → cr_skills |
| `cr_skill_mcps` | skill_id → cr_skills | mcp_id → cr_mcps |
| `cr_sdk_agents` | sdk_id → cr_sdks | agent_id → cr_agents |
| `cr_sdk_skills` | sdk_id → cr_sdks | skill_id → cr_skills |
| `cr_sdk_mcps` | sdk_id → cr_sdks | mcp_id → cr_mcps |
| `cr_agent_collaborations` | agent_id → cr_agents | collaborator_id → cr_agents |

## Workflow

```
1. DETECTAR órfãos em cada tabela
2. CRIAR backup das linhas a remover
3. MOSTRAR resumo ao utilizador
4. PEDIR confirmação (se não --force)
5. EXECUTAR DELETE em transação
6. VALIDAR integridade
7. REPORTAR resultado
```

## Exemplos

### Dry-run (ver sem executar)
```bash
/descomplicar:db-cleanup --dry-run
```

Output:
```
╔════════════════════════════════════════════════════════════╗
║  DB CLEANUP - DRY RUN                                      ║
╠════════════════════════════════════════════════════════════╣
║  cr_agent_mcps:           12 órfãos detectados             ║
║  cr_agent_lsps:            0 órfãos detectados             ║
║  cr_agent_skills:          3 órfãos detectados             ║
║  cr_skill_mcps:            5 órfãos detectados             ║
║  cr_sdk_agents:            0 órfãos detectados             ║
║  cr_sdk_skills:            2 órfãos detectados             ║
║  cr_sdk_mcps:              0 órfãos detectados             ║
║  cr_agent_collaborations:  1 órfão detectado               ║
╠════════════════════════════════════════════════════════════╣
║  TOTAL: 23 órfãos a remover                                ║
║  Executar sem --dry-run para limpar                        ║
╚════════════════════════════════════════════════════════════╝
```

### Limpeza completa
```bash
/descomplicar:db-cleanup
```

Output:
```
╔════════════════════════════════════════════════════════════╗
║  DB CLEANUP                                                ║
╠════════════════════════════════════════════════════════════╣
║  Backup criado: cr_orphans_backup_20260204_163500          ║
╠════════════════════════════════════════════════════════════╣
║  cr_agent_mcps:           12 → 0 órfãos   ✓                ║
║  cr_agent_skills:          3 → 0 órfãos   ✓                ║
║  cr_skill_mcps:            5 → 0 órfãos   ✓                ║
║  cr_sdk_skills:            2 → 0 órfãos   ✓                ║
║  cr_agent_collaborations:  1 → 0 órfãos   ✓                ║
╠════════════════════════════════════════════════════════════╣
║  TOTAL REMOVIDO: 23 órfãos                                 ║
║  Integridade: ✓ OK                                         ║
╚════════════════════════════════════════════════════════════╝
```

### Tabela específica
```bash
/descomplicar:db-cleanup --table=cr_agent_mcps
```

## SQL Executado

```sql
-- Detecção (para cada tabela)
SELECT COUNT(*) as orphans FROM cr_agent_mcps am
LEFT JOIN cr_agents a ON am.agent_id = a.id
LEFT JOIN cr_mcps m ON am.mcp_id = m.id
WHERE a.id IS NULL OR m.id IS NULL;

-- Backup
CREATE TABLE cr_orphans_backup_YYYYMMDD_HHMMSS AS
SELECT 'cr_agent_mcps' as source_table, am.*
FROM cr_agent_mcps am
LEFT JOIN cr_agents a ON am.agent_id = a.id
LEFT JOIN cr_mcps m ON am.mcp_id = m.id
WHERE a.id IS NULL OR m.id IS NULL;

-- Limpeza
DELETE FROM cr_agent_mcps
WHERE agent_id NOT IN (SELECT id FROM cr_agents)
   OR mcp_id NOT IN (SELECT id FROM cr_mcps);
```

## Integração

- **Skill**: db-maintenance-manager
- **MCP**: desk-crm-v3
- **Relacionado**: /descomplicar:status (detecta órfãos)

## Segurança

- Backup SEMPRE criado antes de DELETE (excepto --no-backup)
- Operações em transação (rollback se erro)
- Log em cr_maintenance_log
- Não remove dados de entidades (apenas relacionamentos)