@luanpdd/kit-mcp 0.2.0 → 0.3.0

package/kit/framework/templates/DEBUG.md

@@ -0,0 +1,164 @@
+# Template de Debug
+
+Template para `.planning/debug/[slug].md` — rastreamento de sessão de debug ativa.
+
+---
+
+## Template do Arquivo
+
+```markdown
+---
+status: gathering | investigating | fixing | verifying | awaiting_human_verify | resolved
+trigger: "[entrada verbatim do usuário]"
+created: [timestamp ISO]
+updated: [timestamp ISO]
+---
+
+## Foco Atual
+<!-- SOBRESCREVER a cada atualização - sempre reflete AGORA -->
+
+hypothesis: [teoria atual sendo testada]
+test: [como está sendo testado]
+expecting: [o que significa o resultado se verdadeiro/falso]
+next_action: [próximo passo imediato]
+
+## Sintomas
+<!-- Escrito durante gathering, depois imutável -->
+
+expected: [o que deveria acontecer]
+actual: [o que realmente acontece]
+errors: [mensagens de erro, se houver]
+reproduction: [como acionar]
+started: [quando quebrou / sempre quebrado]
+
+## Eliminados
+<!-- APENAS APPEND - evita reinvestigação após /clear -->
+
+- hypothesis: [teoria que estava errada]
+  evidence: [o que a refutou]
+  timestamp: [quando eliminado]
+
+## Evidências
+<!-- APENAS APPEND - fatos descobertos durante a investigação -->
+
+- timestamp: [quando encontrado]
+  checked: [o que foi examinado]
+  found: [o que foi observado]
+  implication: [o que isso significa]
+
+## Resolução
+<!-- SOBRESCREVER conforme o entendimento evolui -->
+
+root_cause: [vazio até ser encontrado]
+fix: [vazio até ser aplicado]
+verification: [vazio até ser verificado]
+files_changed: []
+```
+
+---
+
+<section_rules>
+
+**Frontmatter (status, trigger, timestamps):**
+- `status`: SOBRESCREVER - reflete a fase atual
+- `trigger`: IMUTÁVEL - entrada verbatim do usuário, nunca muda
+- `created`: IMUTÁVEL - definido uma vez
+- `updated`: SOBRESCREVER - atualizar a cada mudança
+
+**Foco Atual:**
+- SOBRESCREVER completamente a cada atualização
+- Sempre reflete o que Claude está fazendo AGORA
+- Se Claude ler após /clear, sabe exatamente onde retomar
+- Campos: hypothesis, test, expecting, next_action
+
+**Sintomas:**
+- Escrito durante a fase inicial de gathering
+- IMUTÁVEL após o gathering estar completo
+- Ponto de referência do que estamos tentando corrigir
+- Campos: expected, actual, errors, reproduction, started
+
+**Eliminados:**
+- APENAS APPEND - nunca remover entradas
+- Evita reinvestigação de becos sem saída após reset de contexto
+- Cada entrada: hypothesis, evidência que a refutou, timestamp
+- Crítico para eficiência entre limites de /clear
+
+**Evidências:**
+- APENAS APPEND - nunca remover entradas
+- Fatos descobertos durante a investigação
+- Cada entrada: timestamp, o que foi checado, o que foi encontrado, implicação
+- Constrói o caso para a causa raiz
+
+**Resolução:**
+- SOBRESCREVER conforme o entendimento evolui
+- Pode atualizar múltiplas vezes enquanto correções são tentadas
+- Estado final mostra causa raiz confirmada e correção verificada
+- Campos: root_cause, fix, verification, files_changed
+
+</section_rules>
+
+<lifecycle>
+
+**Criação:** Imediatamente quando /debug é chamado
+- Criar arquivo com trigger da entrada do usuário
+- Definir status como "gathering"
+- Foco Atual: next_action = "gather symptoms"
+- Sintomas: vazio, a ser preenchido
+
+**Durante coleta de sintomas:**
+- Atualizar seção Sintomas conforme o usuário responde perguntas
+- Atualizar Foco Atual com cada pergunta
+- Quando completo: status → "investigating"
+
+**Durante investigação:**
+- SOBRESCREVER Foco Atual com cada hipótese
+- APPEND em Evidências com cada descoberta
+- APPEND em Eliminados quando hipótese for refutada
+- Atualizar timestamp no frontmatter
+
+**Durante correção:**
+- status → "fixing"
+- Atualizar Resolução.root_cause quando confirmado
+- Atualizar Resolução.fix quando aplicado
+- Atualizar Resolução.files_changed
+
+**Durante verificação:**
+- status → "verifying"
+- Atualizar Resolução.verification com resultados
+- Se verificação falhar: status → "investigating", tentar novamente
+
+**Após verificação própria passar:**
+- status → "awaiting_human_verify"
+- Solicitar confirmação explícita do usuário em um checkpoint
+- NÃO mover arquivo para resolvido ainda
+
+**Na resolução:**
+- status → "resolved"
+- Mover arquivo para .planning/debug/resolved/ (somente após usuário confirmar correção)
+
+</lifecycle>
+
+<resume_behavior>
+
+Quando Claude ler este arquivo após /clear:
+
+1. Analisar frontmatter → saber status
+2. Ler Foco Atual → saber exatamente o que estava acontecendo
+3. Ler Eliminados → saber o que NÃO tentar novamente
+4. Ler Evidências → saber o que foi aprendido
+5. Continuar a partir de next_action
+
+O arquivo É o cérebro de debug. Claude deve ser capaz de retomar perfeitamente de qualquer ponto de interrupção.
+
+</resume_behavior>
+
+<size_constraint>
+
+Manter arquivos de debug focados:
+- Entradas de Evidências: 1-2 linhas cada, apenas os fatos
+- Eliminados: breve - hipótese + por que falhou
+- Sem prosa narrativa - apenas dados estruturados
+
+Se as evidências crescerem muito (10+ entradas), considere se está andando em círculos. Verifique Eliminados para garantir que não está repisando o mesmo caminho.
+
+</size_constraint>

package/kit/framework/templates/UAT.md

@@ -0,0 +1,265 @@
+# Template de UAT
+
+Template para `.planning/phases/XX-name/{phase_num}-UAT.md` — rastreamento persistente de sessão UAT.
+
+---
+
+## Template do Arquivo
+
+```markdown
+---
+status: testing | partial | complete | diagnosed
+phase: XX-name
+source: [lista de arquivos SUMMARY.md testados]
+started: [timestamp ISO]
+updated: [timestamp ISO]
+---
+
+## Teste Atual
+<!-- SOBRESCREVER a cada teste - mostra onde estamos -->
+
+number: [N]
+name: [nome do teste]
+expected: |
+  [o que o usuário deve observar]
+awaiting: user response
+
+## Testes
+
+### 1. [Nome do Teste]
+expected: [comportamento observável - o que o usuário deve ver]
+result: [pending]
+
+### 2. [Nome do Teste]
+expected: [comportamento observável]
+result: pass
+
+### 3. [Nome do Teste]
+expected: [comportamento observável]
+result: issue
+reported: "[resposta verbatim do usuário]"
+severity: major
+
+### 4. [Nome do Teste]
+expected: [comportamento observável]
+result: skipped
+reason: [por que foi pulado]
+
+### 5. [Nome do Teste]
+expected: [comportamento observável]
+result: blocked
+blocked_by: server | physical-device | release-build | third-party | prior-phase
+reason: [por que está bloqueado]
+
+...
+
+## Resumo
+
+total: [N]
+passed: [N]
+issues: [N]
+pending: [N]
+skipped: [N]
+blocked: [N]
+
+## Gaps
+
+<!-- Formato YAML para consumo por /planejar-fase --gaps -->
+- truth: "[comportamento esperado do teste]"
+  status: failed
+  reason: "User reported: [resposta verbatim]"
+  severity: blocker | major | minor | cosmetic
+  test: [N]
+  root_cause: ""     # Preenchido pelo diagnóstico
+  artifacts: []      # Preenchido pelo diagnóstico
+  missing: []        # Preenchido pelo diagnóstico
+  debug_session: ""  # Preenchido pelo diagnóstico
+```
+
+---
+
+<section_rules>
+
+**Frontmatter:**
+- `status`: SOBRESCREVER - "testing", "partial" ou "complete"
+- `phase`: IMUTÁVEL - definido na criação
+- `source`: IMUTÁVEL - arquivos SUMMARY sendo testados
+- `started`: IMUTÁVEL - definido na criação
+- `updated`: SOBRESCREVER - atualizar a cada mudança
+
+**Teste Atual:**
+- SOBRESCREVER completamente a cada transição de teste
+- Mostra qual teste está ativo e o que está aguardando
+- Na conclusão: "[testing complete]"
+
+**Testes:**
+- Cada teste: SOBRESCREVER campo result quando o usuário responde
+- Valores de `result`: [pending], pass, issue, skipped, blocked
+- Se issue: adicionar `reported` (verbatim) e `severity` (inferido)
+- Se skipped: adicionar `reason` se fornecida
+- Se blocked: adicionar `blocked_by` (tag) e `reason` (se fornecida)
+
+**Resumo:**
+- SOBRESCREVER contagens após cada resposta
+- Rastreia: total, passed, issues, pending, skipped
+
+**Gaps:**
+- APENAS APPEND quando issue encontrado (formato YAML)
+- Após diagnóstico: preencher `root_cause`, `artifacts`, `missing`, `debug_session`
+- Esta seção alimenta diretamente /planejar-fase --gaps
+
+</section_rules>
+
+<diagnosis_lifecycle>
+
+**Após teste completo (status: complete), se existirem gaps:**
+
+1. Usuário executa diagnóstico (da oferta de verify-work ou manualmente)
+2. Workflow diagnose-issues spawna agentes de debug em paralelo
+3. Cada agente investiga um gap, retorna causa raiz
+4. Seção Gaps do UAT.md é atualizada com diagnóstico:
+   - Cada gap recebe `root_cause`, `artifacts`, `missing`, `debug_session` preenchidos
+5. status → "diagnosed"
+6. Pronto para /planejar-fase --gaps com causas raiz
+
+**Após diagnóstico:**
+```yaml
+## Gaps
+
+- truth: "Comentário aparece imediatamente após envio"
+  status: failed
+  reason: "User reported: funciona mas não aparece até eu recarregar a página"
+  severity: major
+  test: 2
+  root_cause: "useEffect em CommentList.tsx com dependência commentCount faltando"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect com dependência faltando"
+  missing:
+    - "Adicionar commentCount ao array de dependências do useEffect"
+  debug_session: ".planning/debug/comment-not-refreshing.md"
+```
+
+</diagnosis_lifecycle>
+
+<lifecycle>
+
+**Criação:** Quando /verificar-trabalho inicia nova sessão
+- Extrair testes dos arquivos SUMMARY.md
+- Definir status como "testing"
+- Teste Atual aponta para teste 1
+- Todos os testes têm result: [pending]
+
+**Durante teste:**
+- Apresentar teste da seção Teste Atual
+- Usuário responde com confirmação de pass ou descrição de issue
+- Atualizar result do teste (pass/issue/skipped)
+- Atualizar contagens de Resumo
+- Se issue: append à seção Gaps (formato YAML), inferir severity
+- Mover Teste Atual para o próximo teste pendente
+
+**Na conclusão:**
+- status → "complete"
+- Teste Atual → "[testing complete]"
+- Commit do arquivo
+- Apresentar resumo com próximos passos
+
+**Conclusão parcial:**
+- status → "partial" (se testes pendentes, bloqueados ou pulados não resolvidos restarem)
+- Teste Atual → "[testing paused — {N} items outstanding]"
+- Commit do arquivo
+- Apresentar resumo com itens pendentes destacados
+
+**Retomando sessão parcial:**
+- `/verificar-trabalho {fase}` retoma a partir do primeiro teste pendente/bloqueado
+- Quando todos os itens forem resolvidos, status avança para "complete"
+
+**Retomar após /clear:**
+1. Ler frontmatter → saber fase e status
+2. Ler Teste Atual → saber onde estamos
+3. Encontrar primeiro result [pending] → continuar a partir daí
+4. Resumo mostra progresso até agora
+
+</lifecycle>
+
+<severity_guide>
+
+A severity é INFERIDA da linguagem natural do usuário, nunca perguntada.
+
+| Usuário descreve | Inferir |
+|----------------|-------|
+| Crash, erro, exception, falha completa, inutilizável | blocker |
+| Não funciona, nada acontece, comportamento errado, faltando | major |
+| Funciona mas..., lento, estranho, menor, pequeno problema | minor |
+| Cor, fonte, espaçamento, alinhamento, visual, parece errado | cosmetic |
+
+Padrão: **major** (padrão seguro, usuário pode corrigir se errado)
+
+</severity_guide>
+
+<good_example>
+```markdown
+---
+status: diagnosed
+phase: 04-comments
+source: 04-01-SUMMARY.md, 04-02-SUMMARY.md
+started: 2025-01-15T10:30:00Z
+updated: 2025-01-15T10:45:00Z
+---
+
+## Teste Atual
+
+[testing complete]
+
+## Testes
+
+### 1. Visualizar Comentários no Post
+expected: Seção de comentários expande, mostra contagem e lista de comentários
+result: pass
+
+### 2. Criar Comentário de Nível Superior
+expected: Enviar comentário via editor de texto rico, aparece na lista com info do autor
+result: issue
+reported: "funciona mas não aparece até eu recarregar a página"
+severity: major
+
+### 3. Responder a um Comentário
+expected: Clicar em Responder, compositor inline aparece, envio mostra resposta aninhada
+result: pass
+
+### 4. Aninhamento Visual
+expected: Thread de 3+ níveis mostra indentação, bordas laterais, limita em profundidade razoável
+result: pass
+
+### 5. Excluir Próprio Comentário
+expected: Clicar em excluir no próprio comentário, removido ou mostra [deleted] se tiver respostas
+result: pass
+
+### 6. Contagem de Comentários
+expected: Post mostra contagem precisa, incrementa ao adicionar comentário
+result: pass
+
+## Resumo
+
+total: 6
+passed: 5
+issues: 1
+pending: 0
+skipped: 0
+
+## Gaps
+
+- truth: "Comentário aparece imediatamente após envio na lista"
+  status: failed
+  reason: "User reported: funciona mas não aparece até eu recarregar a página"
+  severity: major
+  test: 2
+  root_cause: "useEffect em CommentList.tsx com dependência commentCount faltando"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect com dependência faltando"
+  missing:
+    - "Adicionar commentCount ao array de dependências do useEffect"
+  debug_session: ".planning/debug/comment-not-refreshing.md"
+```
+</good_example>

package/kit/framework/templates/UI-SPEC.md

@@ -0,0 +1,100 @@
+---
+phase: {N}
+slug: {phase-slug}
+status: draft
+shadcn_initialized: false
+preset: none
+created: {date}
+---
+
+# Fase {N} — Contrato de Design de UI
+
+> Contrato visual e de interação para fases de frontend. Gerado por ui-researcher, verificado por ui-checker.
+
+---
+
+## Sistema de Design
+
+| Propriedade | Valor |
+|-------------|-------|
+| Ferramenta | {shadcn / none} |
+| Preset | {string do preset ou "não aplicável"} |
+| Biblioteca de componentes | {radix / base-ui / none} |
+| Biblioteca de ícones | {biblioteca} |
+| Fonte | {fonte} |
+
+---
+
+## Escala de Espaçamento
+
+Valores declarados (devem ser múltiplos de 4):
+
+| Token | Valor | Uso |
+|-------|-------|-----|
+| xs | 4px | Espaçamentos de ícones, padding inline |
+| sm | 8px | Espaçamento compacto de elementos |
+| md | 16px | Espaçamento padrão de elementos |
+| lg | 24px | Padding de seção |
+| xl | 32px | Espaços de layout |
+| 2xl | 48px | Quebras principais de seção |
+| 3xl | 64px | Espaçamento de nível de página |
+
+Exceções: {listar quaisquer, ou "nenhuma"}
+
+---
+
+## Tipografia
+
+| Papel | Tamanho | Peso | Altura de Linha |
+|-------|---------|------|-----------------|
+| Body | {px} | {weight} | {ratio} |
+| Label | {px} | {weight} | {ratio} |
+| Heading | {px} | {weight} | {ratio} |
+| Display | {px} | {weight} | {ratio} |
+
+---
+
+## Cores
+
+| Papel | Valor | Uso |
+|-------|-------|-----|
+| Dominante (60%) | {hex} | Fundo, superfícies |
+| Secundário (30%) | {hex} | Cards, sidebar, nav |
+| Destaque (10%) | {hex} | {listar elementos específicos apenas} |
+| Destrutivo | {hex} | Somente ações destrutivas |
+
+Destaque reservado para: {lista explícita — nunca "todos os elementos interativos"}
+
+---
+
+## Contrato de Copywriting
+
+| Elemento | Texto |
+|----------|-------|
+| CTA Principal | {verbo + substantivo específico} |
+| Título de estado vazio | {texto} |
+| Corpo de estado vazio | {texto + próximo passo} |
+| Estado de erro | {problema + caminho para solução} |
+| Confirmação destrutiva | {nome da ação}: {texto de confirmação} |
+
+---
+
+## Segurança de Registry
+
+| Registry | Blocos Usados | Gate de Segurança |
+|----------|---------------|-------------------|
+| shadcn oficial | {lista} | não necessário |
+| {nome de terceiro} | {lista} | visualização shadcn + diff necessário |
+
+---
+
+## Aprovação do Checker
+
+- [ ] Dimensão 1 Copywriting: PASS
+- [ ] Dimensão 2 Visuais: PASS
+- [ ] Dimensão 3 Cores: PASS
+- [ ] Dimensão 4 Tipografia: PASS
+- [ ] Dimensão 5 Espaçamento: PASS
+- [ ] Dimensão 6 Segurança de Registry: PASS
+
+**Aprovação:** {pending / approved YYYY-MM-DD}

package/kit/framework/templates/VALIDATION.md

@@ -0,0 +1,76 @@
+---
+phase: {N}
+slug: {phase-slug}
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: {date}
+---
+
+# Fase {N} — Estratégia de Validação
+
+> Contrato de validação por fase para amostragem de feedback durante a execução.
+
+---
+
+## Infraestrutura de Testes
+
+| Propriedade | Valor |
+|-------------|-------|
+| **Framework** | {pytest 7.x / jest 29.x / vitest / go test / outro} |
+| **Arquivo de config** | {caminho ou "nenhum — Wave 0 instala"} |
+| **Comando de execução rápida** | `{comando rápido}` |
+| **Comando de suite completa** | `{comando completo}` |
+| **Tempo estimado** | ~{N} segundos |
+
+---
+
+## Taxa de Amostragem
+
+- **Após cada commit de tarefa:** Execute `{comando de execução rápida}`
+- **Após cada wave do plano:** Execute `{comando de suite completa}`
+- **Antes de `/verificar-trabalho`:** Suite completa deve estar verde
+- **Latência máxima de feedback:** {N} segundos
+
+---
+
+## Mapa de Verificação Por Tarefa
+
+| ID da Tarefa | Plano | Wave | Requisito | Tipo de Teste | Comando Automatizado | Arquivo Existe | Status |
+|--------------|-------|------|-----------|---------------|---------------------|----------------|--------|
+| {N}-01-01 | 01 | 1 | REQ-{XX} | unit | `{comando}` | ✅ / ❌ W0 | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Requisitos do Wave 0
+
+- [ ] `{tests/test_file.py}` — stubs para REQ-{XX}
+- [ ] `{tests/conftest.py}` — fixtures compartilhadas
+- [ ] `{framework install}` — se nenhum framework detectado
+
+*Se nenhum: "Infraestrutura existente cobre todos os requisitos da fase."*
+
+---
+
+## Verificações Somente Manuais
+
+| Comportamento | Requisito | Por que Manual | Instruções de Teste |
+|---------------|-----------|----------------|---------------------|
+| {comportamento} | REQ-{XX} | {motivo} | {passos} |
+
+*Se nenhum: "Todos os comportamentos da fase têm verificação automatizada."*
+
+---
+
+## Aprovação de Validação
+
+- [ ] Todas as tarefas têm verify `<automated>` ou dependências Wave 0
+- [ ] Continuidade de amostragem: sem 3 tarefas consecutivas sem verificação automatizada
+- [ ] Wave 0 cobre todas as referências MISSING
+- [ ] Sem flags de modo watch
+- [ ] Latência de feedback < {N}s
+- [ ] `nyquist_compliant: true` definido no frontmatter
+
+**Aprovação:** {pending / approved YYYY-MM-DD}