up-cc 0.3.3 → 0.4.1

package/workflows/executar-plano.md

@@ -1,5 +1,11 @@
 <purpose>
 Executar um prompt de fase (PLAN.md) e criar o resumo do resultado (SUMMARY.md).
+
+**PRINCIPIO CENTRAL: Verificacao funcional por task.**
+Cada task NAO esta completa ate que funcione DE VERDADE — nao apenas que o arquivo exista.
+Backend task → curl o endpoint, verificar resposta.
+Frontend task → abrir no browser, verificar que renderiza e interage.
+Integracao → verificar que frontend chama backend corretamente.
 </purpose>
 
 <required_reading>
@@ -20,6 +26,122 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 Extrair do init JSON: `commit_docs`, `phase_dir`, `phase_number`, `plans`, `summaries`, `incomplete_plans`, `state_path`, `config_path`.
 
 Se `.plano/` faltando: erro.
+
+**Detectar modo de execucao:**
+
+```bash
+BUILDER_MODE=$(node -e "try{const c=JSON.parse(require('fs').readFileSync('.plano/config.json','utf8'));console.log(c.builder_mode===true?'true':'false')}catch{console.log('false')}" 2>/dev/null)
+```
+
+Tambem verificar se o prompt contem `<builder_mode>`. Se sim: `$BUILDER_MODE = true`.
+
+**Quando `$BUILDER_MODE = true`:**
+- NAO usar AskUserQuestion em nenhum momento
+- NAO mostrar menus de "Proximo" ou sugerir comandos
+- NAO parar pra pedir confirmacao (Regra 4 → decidir autonomamente)
+- Retornar resultado silenciosamente para o orquestrador
+</step>
+
+<step name="setup_test_data">
+## CRITICO: Criar Dados de Teste ANTES de Executar Tasks
+
+Se o projeto tem banco de dados (Supabase, Postgres, SQLite, etc.), criar dados de teste para poder verificar funcionalidades.
+
+**Detectar banco:**
+```bash
+# Supabase
+grep -r "SUPABASE_URL\|supabase" .env* package.json 2>/dev/null | head -3
+
+# Prisma
+ls prisma/schema.prisma 2>/dev/null
+
+# Drizzle
+ls drizzle.config.* 2>/dev/null
+
+# SQLite
+find . -name "*.db" -o -name "*.sqlite" 2>/dev/null | head -3
+```
+
+**Se banco disponivel e vazio (projeto novo/greenfield):**
+
+1. Rodar migrations pendentes:
+```bash
+npx prisma migrate dev 2>/dev/null || npx supabase db push 2>/dev/null || npx drizzle-kit push 2>/dev/null
+```
+
+2. Criar usuario de teste (se sistema tem auth):
+```bash
+# Via Supabase CLI
+npx supabase functions invoke create-test-user 2>/dev/null
+
+# Ou via API do proprio app (se signup endpoint existe)
+curl -s -X POST http://localhost:$DEV_PORT/api/auth/signup \
+  -H "Content-Type: application/json" \
+  -d '{"email":"teste@teste.com","password":"Teste123!","name":"Usuario Teste"}'
+
+# Ou via SQL direto (Supabase)
+# INSERT INTO auth.users ...
+```
+
+**Dados de teste padrao:**
+
+| Tipo | Dados |
+|------|-------|
+| **Admin** | admin@teste.com / Admin123! / role: admin |
+| **Usuario** | user@teste.com / User123! / role: user |
+| **Nomes** | Usar nomes realistas (Maria Silva, Joao Santos) |
+| **Valores** | Numeros redondos (100, 250, 1000) |
+| **Datas** | Data atual ou proxima semana |
+| **Textos** | "Teste automatico - [dominio]" |
+
+3. Criar seed data do dominio (se seed script existe):
+```bash
+npm run db:seed 2>/dev/null || npx prisma db seed 2>/dev/null || npx tsx prisma/seed.ts 2>/dev/null
+```
+
+4. Se NAO existe seed script: criar dados via API apos endpoints estarem prontos (durante execucao das tasks)
+
+**Salvar credenciais de teste para uso durante verificacao:**
+```
+$TEST_ADMIN_EMAIL = "admin@teste.com"
+$TEST_ADMIN_PASSWORD = "Admin123!"
+$TEST_USER_EMAIL = "user@teste.com"
+$TEST_USER_PASSWORD = "User123!"
+```
+
+**Se banco NAO disponivel ou sem acesso:** Pular. Registrar como `[PRECISA-CREDENCIAL]`.
+
+</step>
+
+<step name="start_dev_server">
+## CRITICO: Subir Dev Server ANTES de Executar Qualquer Task
+
+Detectar e subir o servidor de desenvolvimento:
+
+```bash
+# Detectar comando de dev
+if [ -f package.json ]; then
+  DEV_CMD=$(node -e "const p=require('./package.json'); const s=p.scripts||{}; console.log(s.dev||s.start||'')")
+fi
+
+# Subir em background
+if [ -n "$DEV_CMD" ]; then
+  npm run dev > /tmp/up-dev-server.log 2>&1 &
+  DEV_PID=$!
+
+  # Esperar ficar pronto (max 30s)
+  PORT=$(node -e "const p=require('./package.json'); const s=p.scripts||{}; const d=s.dev||''; const m=d.match(/--port\s+(\d+)|PORT=(\d+)/); console.log(m?m[1]||m[2]:'3000')" 2>/dev/null || echo "3000")
+  for i in $(seq 1 30); do
+    curl -s http://localhost:$PORT > /dev/null 2>&1 && break
+    sleep 1
+  done
+fi
+```
+
+Se o servidor subiu: `$DEV_SERVER_ACTIVE = true`, `$DEV_PORT = $PORT`
+Se nao subiu: `$DEV_SERVER_ACTIVE = false` — continuar sem verificacao funcional runtime (fallback para verificacao estatica)
+
+**Manter o servidor rodando durante TODA a execucao do plano.**
 </step>
 
 <step name="identify_plan">
@@ -58,13 +180,200 @@ Desvios sao normais -- tratar via regras abaixo.
 
 1. Ler arquivos de @contexto do prompt
 2. Por tarefa:
-   - `type="auto"`: Implementar com regras de desvio + portoes de autenticacao. Verificar criterios de conclusao. Commitar. Registrar hash para Summary.
-   - `type="checkpoint:*"`: PARAR -> checkpoint_protocol -> esperar usuario -> continuar apenas apos confirmacao.
+   - `type="auto"`: Implementar → **verificar funcionalmente** → commitar → registrar
+   - `type="checkpoint:*"`: PARAR -> checkpoint_protocol -> esperar usuario -> continuar
 3. Executar verificacoes `<verification>`
 4. Confirmar `<success_criteria>` atendido
 5. Documentar desvios no Summary
 </step>
 
+<runtime_verification>
+## VERIFICACAO FUNCIONAL POR TASK (CRITICO)
+
+**Apos CADA task implementada, ANTES de commitar, verificar que FUNCIONA:**
+
+### Task de Backend (API route, endpoint, middleware)
+
+```bash
+# 1. Verificar que o servidor recarregou (hot reload)
+sleep 2
+
+# 2. Se endpoint requer auth, fazer login primeiro com usuario de teste
+# Usar credenciais criadas no step setup_test_data
+AUTH_TOKEN=""
+if [endpoint requer auth]; then
+  AUTH_RESPONSE=$(curl -s -X POST http://localhost:$DEV_PORT/api/auth/login \
+    -H "Content-Type: application/json" \
+    -d "{\"email\":\"$TEST_ADMIN_EMAIL\",\"password\":\"$TEST_ADMIN_PASSWORD\"}")
+  AUTH_TOKEN=$(echo $AUTH_RESPONSE | node -e "process.stdin.on('data',d=>{try{console.log(JSON.parse(d).token||JSON.parse(d).data?.token||'')}catch{console.log('')}})")
+fi
+
+# 3. Testar o endpoint criado/modificado
+curl -s -X POST http://localhost:$DEV_PORT/api/messages \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $AUTH_TOKEN" \
+  -d '{"content":"teste automatico"}' \
+  -w "\n%{http_code}"
+
+# 4. Verificar response
+# - Status code correto (200, 201, etc.)?
+# - Response body tem a estrutura esperada?
+# - Nao retornou 500 ou erro?
+# - Se 401: credencial de teste invalida ou auth middleware errado
+```
+
+**Se resposta inesperada:**
+1. Ler log do servidor: `tail -20 /tmp/up-dev-server.log`
+2. Identificar erro (import faltando, typo, tipo errado)
+3. Corrigir inline
+4. Re-testar (max 3 tentativas)
+5. Se ainda falha: registrar como issue e continuar
+
+### Task de Frontend (componente, pagina, UI)
+
+Se Playwright MCP disponivel:
+```
+browser_navigate(url: "http://localhost:$DEV_PORT/[rota]")
+browser_snapshot()
+```
+
+Verificar:
+- Pagina renderiza sem erro? (nao tela branca)
+- Componente esperado existe no snapshot?
+- Console sem erros? `browser_console_messages(level: "error")`
+
+Se Playwright NAO disponivel:
+```bash
+# Fallback: verificar que a pagina responde
+curl -s http://localhost:$DEV_PORT/[rota] | head -20
+# Deve retornar HTML, nao erro
+```
+
+**Se tela branca ou erro:**
+1. Checar console/logs
+2. Corrigir (import faltando, componente errado, props faltando)
+3. Re-testar (max 3 tentativas)
+
+### Task de Integracao (frontend chamando backend)
+
+```
+# 0. Se pagina requer auth, fazer login primeiro via Playwright
+if [rota protegida]:
+  browser_navigate(url: "http://localhost:$DEV_PORT/login")
+  browser_snapshot()
+  browser_fill_form(fields: [
+    {ref: "[email-input]", value: "$TEST_ADMIN_EMAIL"},
+    {ref: "[password-input]", value: "$TEST_ADMIN_PASSWORD"}
+  ])
+  browser_click(ref: "[submit-button]")
+  # Esperar redirect pos-login
+  browser_snapshot()  # deve estar na pagina protegida agora
+
+# 1. Navegar para a pagina
+browser_navigate(url: "http://localhost:$DEV_PORT/[rota]")
+
+# 2. Interagir (clicar botao, submeter form)
+browser_snapshot()
+browser_click(ref: "[ref-do-botao]")
+# ou
+browser_fill_form(fields: [...])
+browser_press_key(key: "Enter")
+
+# 3. Verificar que a acao funcionou
+browser_snapshot()  # novo estado
+browser_network_requests()  # API foi chamada?
+
+# 4. Checar erros
+browser_console_messages(level: "error")
+```
+
+**Se a acao nao funcionou:**
+1. Checar network requests — API retornou erro?
+2. Checar console — erro no frontend?
+3. Comparar URL do fetch com a rota real do backend
+4. Corrigir conexao frontend↔backend
+5. Re-testar (max 3 tentativas)
+
+### Task de Database (schema, migration, seed)
+
+```bash
+# Verificar que migration rodou
+npx prisma migrate status 2>/dev/null || npx supabase db push --dry-run 2>/dev/null
+
+# Verificar que seed populou
+# (se seed task)
+curl -s http://localhost:$DEV_PORT/api/[recurso] | head -5
+# Deve retornar dados, nao lista vazia
+```
+
+### Quando Pular Verificacao Funcional
+
+- Task de config/setup (tsconfig, eslint, deps): pular
+- Task de types/interfaces only: pular
+- Task de testes (escrita de testes): pular (testes sao a verificacao)
+- `$DEV_SERVER_ACTIVE = false`: pular runtime, usar verificacao estatica
+
+### Quando Precisa de Credencial/Acesso Externo
+
+Se a verificacao requer algo que o executor NAO tem:
+- Cookies de sessao do usuario (Instagram, WhatsApp, etc.)
+- Login em servico externo (dashboard de terceiro, admin panel externo)
+- Token OAuth com permissoes especificas
+- Acesso fisico (camera, microfone, GPS)
+- Pagamento real (testar checkout com cartao)
+
+**NAO perguntar ao usuario. NAO parar o builder.**
+
+Em vez disso:
+1. Testar o maximo possivel SEM a credencial (mock, dados locais, dry-run)
+2. Registrar no SUMMARY.md como `[PRECISA-CREDENCIAL]`:
+
+```markdown
+## Verificacoes Pendentes (Credenciais Necessarias)
+
+| Task | O que testar | Credencial necessaria | Como obter |
+|------|-------------|----------------------|-----------|
+| 3 | Integração Instagram | Cookie de sessão Instagram | Login manual no Playwright |
+| 5 | Webhook WhatsApp | Token UazAPI configurado | Configurar em .env |
+| 7 | Checkout Stripe | Chave de teste Stripe | Dashboard Stripe > API Keys |
+```
+
+Estas verificacoes serao agregadas no DELIVERY.md na secao "Testes Pendentes de Credenciais".
+
+### Verificacao Estatica (Fallback)
+
+Se dev server nao esta ativo:
+```bash
+# TypeScript compila?
+npx tsc --noEmit 2>&1 | tail -10
+
+# ESLint passa?
+npx eslint src/ --quiet 2>&1 | tail -10
+
+# Build funciona?
+npm run build 2>&1 | tail -10
+```
+
+</runtime_verification>
+
+<task_completion_protocol>
+## Protocolo de Conclusao por Task
+
+Uma task SO esta completa quando:
+
+1. **Codigo escrito** — arquivo(s) criado(s)/modificado(s)
+2. **Verificacao funcional PASSOU** — endpoint responde / pagina renderiza / acao funciona
+3. **Commit feito** — atomico, com mensagem descritiva
+4. **Hash registrado** — para o SUMMARY
+
+Se verificacao funcional FALHA apos 3 tentativas:
+- Registrar como `[FUNCIONAL-FALHA]` no SUMMARY com descricao do problema
+- Commitar o que tem (codigo pode estar correto mas dependencia de outra task)
+- Continuar para proxima task
+- O code reviewer (Reflect step) vai pegar isso depois
+
+</task_completion_protocol>
+
 <deviation_rules>
 
 ## Regras de Desvio
@@ -76,16 +385,26 @@ Voce VAI descobrir trabalho nao planejado. Aplicar automaticamente, rastrear tod
 | **1: Bug** | Comportamento quebrado, erros, queries erradas, erros de tipo, vulns de seguranca | Corrigir -> testar -> verificar -> rastrear `[Regra 1 - Bug]` | Auto |
 | **2: Critico Faltante** | Essenciais faltando: tratamento de erro, validacao, auth, CSRF/CORS | Adicionar -> testar -> verificar -> rastrear `[Regra 2 - Critico Faltante]` | Auto |
 | **3: Bloqueante** | Impede conclusao: deps faltando, tipos errados, imports quebrados | Corrigir bloqueio -> verificar que prossegue -> rastrear `[Regra 3 - Bloqueante]` | Auto |
-| **4: Arquitetural** | Mudanca estrutural: nova tabela DB, mudanca de schema, novo servico | PARAR -> apresentar decisao -> rastrear `[Regra 4 - Arquitetural]` | Perguntar usuario |
+| **4: Arquitetural** | Mudanca estrutural: nova tabela DB, mudanca de schema, novo servico | **Se $BUILDER_MODE:** decidir autonomamente → rastrear `[Regra 4 - Arquitetural (auto)]`. **Se modo normal:** PARAR → apresentar decisao → rastrear. | Perguntar (normal) / Auto (builder) |
+| **5: Conexao Frontend↔Backend** | Frontend chama URL errada, payload errado, response shape diferente | Corrigir URL/payload/parsing -> re-testar -> rastrear `[Regra 5 - Conexao]` | Auto |
+
+**Regra 5 e NOVA e CRITICA.** A maioria dos problemas "nada funciona" vem de:
+- Frontend fazendo fetch para `/api/messages` mas backend tem `/api/message` (sem s)
+- Frontend enviando `{ message: "oi" }` mas backend espera `{ content: "oi" }`
+- Frontend esperando `response.data.messages` mas backend retorna `response.messages`
+- Frontend usando `GET` mas backend espera `POST`
+- CORS bloqueando a requisicao
+
+**SEMPRE verificar**: URL + metodo HTTP + payload shape + response shape + CORS.
 
-**Prioridade:** Regra 4 (PARAR) > Regras 1-3 (auto) > incerto -> Regra 4
+**Prioridade:** Regra 4 (PARAR) > Regra 5 (conexao) > Regras 1-3 (auto) > incerto -> Regra 4
 
 </deviation_rules>
 
 <task_commit>
 ## Protocolo de Commit por Tarefa
 
-Apos cada tarefa (verificacao passou, criterios de conclusao atendidos), commitar imediatamente.
+Apos cada tarefa (verificacao funcional PASSOU, criterios de conclusao atendidos), commitar imediatamente.
 
 **1. Verificar:** `git status --short`
 
@@ -127,6 +446,47 @@ Exibir: box `CHECKPOINT: [Tipo]` -> Progresso {X}/{Y} -> Nome da tarefa -> conte
 | human-action (1%) | O que foi automatizado + UM passo manual | "feito" |
 </step>
 
+<step name="wave_integration_check">
+## Verificacao de Integracao por Wave
+
+**Apos TODAS as tasks de uma wave completarem**, verificar que as pecas se conectam:
+
+```bash
+# 1. App ainda roda? (hot reload pode ter quebrado)
+curl -s http://localhost:$DEV_PORT/ > /dev/null 2>&1
+if [ $? -ne 0 ]; then
+  echo "DEV SERVER CAIU — reiniciando"
+  npm run dev > /tmp/up-dev-server.log 2>&1 &
+  DEV_PID=$!
+  sleep 5
+fi
+```
+
+Se Playwright disponivel:
+```
+# 2. Navegar para pagina principal da feature
+browser_navigate(url: "http://localhost:$DEV_PORT/[rota-principal]")
+browser_snapshot()
+
+# 3. Verificar que nao ha erros de console
+browser_console_messages(level: "error")
+
+# 4. Verificar que dados carregam (se aplicavel)
+# O snapshot deve mostrar dados reais, nao loading infinito ou erro
+
+# 5. Tentar interacao basica
+browser_click(ref: "[botao-principal]")  # se existir
+browser_snapshot()  # verificar resultado
+```
+
+**Se integracao quebrada:**
+- Identificar: e problema de URL? payload? auth? CORS?
+- Corrigir (Regra 5 de desvio)
+- Re-testar
+- Commitar fix: `fix({fase}-{plano}): corrigir integracao [descricao]`
+
+</step>
+
 <step name="create_summary">
 Criar `{fase}-{plano}-SUMMARY.md` em `.plano/fases/XX-nome/`.
 
@@ -135,6 +495,28 @@ Criar `{fase}-{plano}-SUMMARY.md` em `.plano/fases/XX-nome/`.
 Titulo: `# Fase [X] Plano [Y]: [Nome] Resumo`
 
 One-liner SUBSTANCIAL: "Auth JWT com rotacao de refresh usando jose library" nao "Autenticacao implementada"
+
+**NOVO — Secao de verificacao funcional no SUMMARY:**
+
+```markdown
+## Verificacao Funcional
+
+| Task | Tipo | Verificacao | Resultado |
+|------|------|------------|-----------|
+| 1 | backend | curl POST /api/messages → 201 | PASSOU |
+| 2 | frontend | /chat renderiza, input existe | PASSOU |
+| 3 | integracao | enviar mensagem → aparece na lista | PASSOU |
+| 4 | backend | curl GET /api/messages → 200 + array | PASSOU |
+
+**Dev server:** ativo na porta {PORT}
+**Problemas de conexao frontend↔backend:** {0 | N encontrados e corrigidos}
+```
+</step>
+
+<step name="cleanup_dev_server">
+**NAO matar o dev server ao finalizar o plano.**
+O proximo plano da mesma fase vai precisar dele.
+O servidor so e morto no final da FASE (pelo orquestrador executar-fase.md).
 </step>
 
 <step name="update_current_position">
@@ -169,6 +551,20 @@ node "$HOME/.claude/up/bin/up-tools.cjs" commit "docs({fase}-{plano}): completar
 </step>
 
 <step name="offer_next">
+
+**Se $BUILDER_MODE = true:**
+NAO mostrar menus ou sugerir proximos passos. Retornar resultado silenciosamente:
+```markdown
+## PLANO COMPLETO
+
+**Plano:** {fase}-{plano}
+**Tarefas:** {completadas}/{total}
+**Verificacao funcional:** {passed}/{total}
+```
+O orquestrador do builder controla o que vem depois. FIM.
+
+**Se modo normal (interativo):**
+
 ```bash
 ls -1 .plano/fases/[dir-fase-atual]/*-PLAN.md 2>/dev/null | wc -l
 ls -1 .plano/fases/[dir-fase-atual]/*-SUMMARY.md 2>/dev/null | wc -l
@@ -185,8 +581,10 @@ ls -1 .plano/fases/[dir-fase-atual]/*-SUMMARY.md 2>/dev/null | wc -l
 
 <success_criteria>
 - Todas tarefas do PLAN.md completadas
+- **Verificacao funcional passou por task (endpoint responde, pagina renderiza, acao funciona)**
+- **Integracao frontend↔backend verificada**
 - Todas verificacoes passam
-- SUMMARY.md criado com conteudo substancial
+- SUMMARY.md criado com conteudo substancial E secao de verificacao funcional
 - STATE.md atualizado (posicao, decisoes, problemas, sessao)
 - ROADMAP.md atualizado
 </success_criteria>