@luanpdd/kit-mcp 0.2.1 → 0.3.0

package/kit/framework/templates/verification-report.md

@@ -0,0 +1,258 @@
+# Template de Relatório de Verificação
+
+Template para `.planning/phases/XX-name/{phase_num}-VERIFICATION.md` — resultados de verificação do objetivo da fase.
+
+---
+
+## Template do Arquivo
+
+```markdown
+---
+phase: XX-name
+verified: YYYY-MM-DDTHH:MM:SSZ
+status: passed | gaps_found | human_needed
+score: N/M must-haves verificados
+---
+
+# Fase {X}: {Nome} — Relatório de Verificação
+
+**Objetivo da Fase:** {objetivo do ROADMAP.md}
+**Verificado:** {timestamp}
+**Status:** {passed | gaps_found | human_needed}
+
+## Atingimento do Objetivo
+
+### Verdades Observáveis
+
+| # | Verdade | Status | Evidência |
+|---|---------|--------|-----------|
+| 1 | {verdade dos must_haves} | ✓ VERIFICADO | {o que confirmou} |
+| 2 | {verdade dos must_haves} | ✗ FALHOU | {o que está errado} |
+| 3 | {verdade dos must_haves} | ? INCERTO | {por que não pode verificar} |
+
+**Pontuação:** {N}/{M} verdades verificadas
+
+### Artefatos Necessários
+
+| Artefato | Esperado | Status | Detalhes |
+|----------|----------|--------|---------|
+| `src/components/Chat.tsx` | Componente de lista de mensagens | ✓ EXISTE + SUBSTANCIAL | Exporta ChatList, renderiza Message[], sem stubs |
+| `src/app/api/chat/route.ts` | CRUD de mensagens | ✗ STUB | Arquivo existe mas POST retorna placeholder |
+| `prisma/schema.prisma` | Model de Message | ✓ EXISTE + SUBSTANCIAL | Model definido com todos os campos |
+
+**Artefatos:** {N}/{M} verificados
+
+### Verificação de Conexões Chave
+
+| De | Para | Via | Status | Detalhes |
+|----|------|-----|--------|---------|
+| Chat.tsx | /api/chat | fetch in useEffect | ✓ CONECTADO | Linha 23: `fetch('/api/chat')` com tratamento de resposta |
+| ChatInput | /api/chat POST | onSubmit handler | ✗ NÃO CONECTADO | onSubmit apenas chama console.log |
+| /api/chat POST | database | prisma.message.create | ✗ NÃO CONECTADO | Retorna resposta hardcoded, sem chamada ao DB |
+
+**Conexões:** {N}/{M} verificadas
+
+## Cobertura de Requisitos
+
+| Requisito | Status | Problema Bloqueante |
+|-----------|--------|---------------------|
+| {REQ-01}: {descrição} | ✓ SATISFEITO | - |
+| {REQ-02}: {descrição} | ✗ BLOQUEADO | Rota da API é stub |
+| {REQ-03}: {descrição} | ? PRECISA HUMANO | Não é possível verificar WebSocket programaticamente |
+
+**Cobertura:** {N}/{M} requisitos satisfeitos
+
+## Anti-Padrões Encontrados
+
+| Arquivo | Linha | Padrão | Severidade | Impacto |
+|---------|-------|--------|------------|---------|
+| src/app/api/chat/route.ts | 12 | `// TODO: implement` | ⚠️ Alerta | Indica incompleto |
+| src/components/Chat.tsx | 45 | `return <div>Placeholder</div>` | 🛑 Bloqueador | Não renderiza conteúdo |
+| src/hooks/useChat.ts | - | Arquivo faltando | 🛑 Bloqueador | Hook esperado não existe |
+
+**Anti-padrões:** {N} encontrados ({blockers} bloqueadores, {warnings} alertas)
+
+## Verificação Humana Necessária
+
+{Se nenhuma verificação humana necessária:}
+Nenhuma — todos os itens verificáveis foram verificados programaticamente.
+
+{Se verificação humana necessária:}
+
+### 1. {Nome do Teste}
+**Teste:** {O que fazer}
+**Esperado:** {O que deve acontecer}
+**Por que humano:** {Por que não pode verificar programaticamente}
+
+### 2. {Nome do Teste}
+**Teste:** {O que fazer}
+**Esperado:** {O que deve acontecer}
+**Por que humano:** {Por que não pode verificar programaticamente}
+
+## Resumo de Lacunas
+
+{Se sem lacunas:}
+**Nenhuma lacuna encontrada.** Objetivo da fase atingido. Pronto para prosseguir.
+
+{Se lacunas encontradas:}
+
+### Lacunas Críticas (Bloqueiam o Progresso)
+
+1. **{Nome da lacuna}**
+   - Faltando: {o que está faltando}
+   - Impacto: {por que isso bloqueia o objetivo}
+   - Correção: {o que precisa acontecer}
+
+2. **{Nome da lacuna}**
+   - Faltando: {o que está faltando}
+   - Impacto: {por que isso bloqueia o objetivo}
+   - Correção: {o que precisa acontecer}
+
+### Lacunas Não-Críticas (Podem Ser Diferidas)
+
+1. **{Nome da lacuna}**
+   - Problema: {o que está errado}
+   - Impacto: {impacto limitado porque...}
+   - Recomendação: {corrigir agora ou diferir}
+
+## Planos de Correção Recomendados
+
+{Se lacunas encontradas, gerar recomendações de plano de correção:}
+
+### {phase}-{next}-PLAN.md: {Nome da Correção}
+
+**Objetivo:** {O que isso corrige}
+
+**Tarefas:**
+1. {Tarefa para corrigir lacuna 1}
+2. {Tarefa para corrigir lacuna 2}
+3. {Tarefa de verificação}
+
+**Escopo estimado:** {Pequeno / Médio}
+
+---
+
+### {phase}-{next+1}-PLAN.md: {Nome da Correção}
+
+**Objetivo:** {O que isso corrige}
+
+**Tarefas:**
+1. {Tarefa}
+2. {Tarefa}
+
+**Escopo estimado:** {Pequeno / Médio}
+
+---
+
+## Metadados de Verificação
+
+**Abordagem de verificação:** Goal-backward (derivada do objetivo da fase)
+**Fonte dos must-haves:** {frontmatter do PLAN.md | derivado do objetivo do ROADMAP.md}
+**Verificações automatizadas:** {N} passaram, {M} falharam
+**Verificações humanas necessárias:** {N}
+**Tempo total de verificação:** {duração}
+
+---
+*Verificado: {timestamp}*
+*Verificador: Claude (subagente)*
+```
+
+---
+
+## Diretrizes
+
+**Valores de status:**
+- `passed` — Todos os must-haves verificados, sem bloqueadores
+- `gaps_found` — Uma ou mais lacunas críticas encontradas
+- `human_needed` — Verificações automatizadas passam mas verificação humana necessária
+
+**Tipos de evidência:**
+- Para EXISTS: "Arquivo no caminho, exporta X"
+- Para SUBSTANTIVE: "N linhas, tem padrões X, Y, Z"
+- Para WIRED: "Linha N: código que conecta A a B"
+- Para FAILED: "Faltando porque X" ou "Stub porque Y"
+
+**Níveis de severidade:**
+- 🛑 Bloqueador: Impede o atingimento do objetivo, deve corrigir
+- ⚠️ Alerta: Indica incompleto mas não bloqueia
+- ℹ️ Info: Notável mas não problemático
+
+**Geração de plano de correção:**
+- Gerar apenas se gaps_found
+- Agrupar correções relacionadas em planos únicos
+- Manter 2-3 tarefas por plano
+- Incluir tarefa de verificação em cada plano
+
+---
+
+## Exemplo
+
+```markdown
+---
+phase: 03-chat
+verified: 2025-01-15T14:30:00Z
+status: gaps_found
+score: 2/5 must-haves verificados
+---
+
+# Fase 3: Interface de Chat — Relatório de Verificação
+
+**Objetivo da Fase:** Interface de chat funcional onde usuários podem enviar e receber mensagens
+**Verificado:** 2025-01-15T14:30:00Z
+**Status:** gaps_found
+
+## Atingimento do Objetivo
+
+### Verdades Observáveis
+
+| # | Verdade | Status | Evidência |
+|---|---------|--------|-----------|
+| 1 | Usuário pode ver mensagens existentes | ✗ FALHOU | Componente renderiza placeholder, não dados de mensagem |
+| 2 | Usuário pode digitar uma mensagem | ✓ VERIFICADO | Campo de input existe com handler onChange |
+| 3 | Usuário pode enviar uma mensagem | ✗ FALHOU | Handler onSubmit é apenas console.log |
+| 4 | Mensagem enviada aparece na lista | ✗ FALHOU | Sem atualização de estado após envio |
+| 5 | Mensagens persistem após atualização | ? INCERTO | Não é possível verificar — envio não funciona |
+
+**Pontuação:** 1/5 verdades verificadas
+
+## Resumo de Lacunas
+
+### Lacunas Críticas (Bloqueiam o Progresso)
+
+1. **Componente de chat é placeholder**
+   - Faltando: Renderização real da lista de mensagens
+   - Impacto: Usuários veem "Chat will be here" em vez de mensagens
+   - Correção: Implementar Chat.tsx para buscar e renderizar mensagens
+
+2. **Rotas da API são stubs**
+   - Faltando: Integração com banco nas rotas GET e POST
+   - Impacto: Sem persistência de dados, sem funcionalidade real
+   - Correção: Conectar chamadas prisma nos handlers de rota
+
+## Planos de Correção Recomendados
+
+### 03-04-PLAN.md: Implementar API de Chat
+
+**Objetivo:** Conectar rotas da API ao banco de dados
+
+**Tarefas:**
+1. Implementar GET /api/chat com prisma.message.findMany
+2. Implementar POST /api/chat com prisma.message.create
+3. Verificar: API retorna dados reais, POST cria registros
+
+**Escopo estimado:** Pequeno
+
+---
+
+## Metadados de Verificação
+
+**Abordagem de verificação:** Goal-backward (derivada do objetivo da fase)
+**Fonte dos must-haves:** frontmatter do 03-01-PLAN.md
+**Verificações automatizadas:** 2 passaram, 8 falharam
+**Verificações humanas necessárias:** 0 (bloqueadas por falhas automatizadas)
+**Tempo total de verificação:** 2 min
+
+---
+*Verificado: 2025-01-15T14:30:00Z*
+*Verificador: Claude (subagente)*
+```

package/kit/framework/workflows/add-phase.md

@@ -0,0 +1,112 @@
+<purpose>
+Adicionar uma nova fase inteira ao final do milestone atual no roadmap. Calcula automaticamente o próximo número de fase, cria o diretório da fase e atualiza a estrutura do roadmap.
+</purpose>
+
+<required_reading>
+Leia todos os arquivos referenciados pelo execution_context do prompt que invocou antes de começar.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Analisar os argumentos do comando:
+- Todos os argumentos se tornam a descrição da fase
+- Exemplo: `/adicionar-fase Adicionar autenticação` → descrição = "Adicionar autenticação"
+- Exemplo: `/adicionar-fase Corrigir problemas críticos de performance` → descrição = "Corrigir problemas críticos de performance"
+
+Se nenhum argumento for fornecido:
+
+```
+ERRO: Descrição da fase obrigatória
+Uso: /adicionar-fase <descrição>
+Exemplo: /adicionar-fase Adicionar sistema de autenticação
+```
+
+Sair.
+</step>
+
+<step name="init_context">
+Carregar contexto de operação de fase:
+
+```bash
+INIT=$(node "./.claude/framework/bin/tools.cjs" init phase-op "0")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Verificar `roadmap_exists` do JSON de init. Se false:
+```
+ERRO: Nenhum roadmap encontrado (.planning/ROADMAP.md)
+Execute /novo-projeto para inicializar.
+```
+Sair.
+</step>
+
+<step name="add_phase">
+**Delegar a adição de fase ao tools:**
+
+```bash
+RESULT=$(node "./.claude/framework/bin/tools.cjs" phase add "${description}")
+```
+
+O CLI gerencia:
+- Encontrar o maior número de fase inteira existente
+- Calcular o próximo número de fase (máx + 1)
+- Gerar slug a partir da descrição
+- Criar o diretório da fase (`.planning/phases/{NN}-{slug}/`)
+- Inserir a entrada de fase no ROADMAP.md com seções de Objetivo, Dependências e Planos
+
+Extrair do resultado: `phase_number`, `padded`, `name`, `slug`, `directory`.
+</step>
+
+<step name="update_project_state">
+Atualizar STATE.md para refletir a nova fase:
+
+1. Leia `.planning/STATE.md`
+2. Em "## Accumulated Context" → "### Roadmap Evolution" adicione entrada:
+   ```
+   - Fase {N} adicionada: {descrição}
+   ```
+
+Se a seção "Roadmap Evolution" não existir, crie-a.
+</step>
+
+<step name="completion">
+Apresentar resumo de conclusão:
+
+```
+Fase {N} adicionada ao milestone atual:
+- Descrição: {descrição}
+- Diretório: .planning/phases/{phase-num}-{slug}/
+- Status: Ainda não planejada
+
+Roadmap atualizado: .planning/ROADMAP.md
+
+---
+
+## ▶ Próximo
+
+**Fase {N}: {descrição}**
+
+`/planejar-fase {N}`
+
+<sub>`/clear` primeiro → janela de contexto limpa</sub>
+
+---
+
+**Também disponível:**
+- `/adicionar-fase <descrição>` — adicionar outra fase
+- Revisar o roadmap
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] `tools phase add` executado com sucesso
+- [ ] Diretório da fase criado
+- [ ] Roadmap atualizado com nova entrada de fase
+- [ ] STATE.md atualizado com nota de evolução do roadmap
+- [ ] Usuário informado sobre próximos passos
+</success_criteria>