sincron-auto 1.0.0

package/docs/exemplos-playwright.md

@@ -0,0 +1,497 @@
+# Exemplos de Comandos Playwright MCP
+
+Este documento fornece exemplos práticos de como usar os comandos Playwright MCP para testes visuais e funcionais.
+
+## Navegação
+
+### Navegar para uma URL
+
+```typescript
+mcp__playwright__navigate({
+  url: "http://localhost:3000"
+})
+```
+
+### Aguardar navegação para URL específica
+
+```typescript
+mcp__playwright__wait_for_url({
+  url: "/dashboard",
+  timeout: 5000  // opcional, em ms
+})
+```
+
+## Query de Elementos
+
+### Buscar elemento por seletor
+
+```typescript
+mcp__playwright__query_selector({
+  selector: "#btn-submit"
+})
+// Retorna: elemento encontrado ou erro se não existir
+```
+
+### Buscar múltiplos elementos
+
+```typescript
+mcp__playwright__query_selector_all({
+  selector: ".task-item"
+})
+// Retorna: array de elementos
+```
+
+## Interações
+
+### Clicar em elemento
+
+```typescript
+mcp__playwright__click({
+  selector: "#btn-submit",
+  timeout: 5000  // opcional
+})
+```
+
+### Preencher campo de input
+
+```typescript
+mcp__playwright__fill({
+  selector: "#email",
+  value: "usuario@exemplo.com"
+})
+```
+
+### Digitar texto (simula digitação real)
+
+```typescript
+mcp__playwright__type({
+  selector: "#search",
+  text: "buscar produto",
+  delay: 100  // delay entre teclas em ms
+})
+```
+
+### Pressionar tecla
+
+```typescript
+mcp__playwright__press({
+  selector: "#search",
+  key: "Enter"
+})
+```
+
+### Selecionar opção em dropdown
+
+```typescript
+mcp__playwright__select_option({
+  selector: "#country",
+  value: "BR"
+})
+```
+
+### Marcar/desmarcar checkbox
+
+```typescript
+mcp__playwright__check({
+  selector: "#accept-terms"
+})
+
+mcp__playwright__uncheck({
+  selector: "#newsletter"
+})
+```
+
+## Captura de Tela
+
+### Screenshot de página inteira
+
+```typescript
+mcp__playwright__screenshot({
+  path: "./screenshots/full-page.png",
+  fullPage: true
+})
+```
+
+### Screenshot de elemento específico
+
+```typescript
+mcp__playwright__screenshot({
+  path: "./screenshots/login-form.png",
+  selector: "#login-form"
+})
+```
+
+## Verificação de CSS e Estilos
+
+### Obter propriedade computada de CSS
+
+```typescript
+mcp__playwright__eval({
+  expression: "getComputedStyle(document.querySelector('#btn-submit')).backgroundColor"
+})
+// Retorna: "rgb(37, 99, 235)"
+```
+
+### Verificar múltiplas propriedades
+
+```typescript
+mcp__playwright__eval({
+  expression: `
+    const btn = document.querySelector('#btn-submit');
+    const style = getComputedStyle(btn);
+    return {
+      backgroundColor: style.backgroundColor,
+      color: style.color,
+      fontSize: style.fontSize,
+      fontFamily: style.fontFamily,
+      padding: style.padding
+    };
+  `
+})
+```
+
+### Verificar alinhamento
+
+```typescript
+mcp__playwright__eval({
+  expression: `
+    const elem = document.querySelector('#login-form');
+    const rect = elem.getBoundingClientRect();
+    const parent = elem.parentElement.getBoundingClientRect();
+
+    // Check if horizontally centered
+    const horizontalCenter = Math.abs(
+      (parent.width / 2) - (rect.left - parent.left + rect.width / 2)
+    ) < 5;
+
+    // Check if vertically centered
+    const verticalCenter = Math.abs(
+      (parent.height / 2) - (rect.top - parent.top + rect.height / 2)
+    ) < 5;
+
+    return { horizontalCenter, verticalCenter };
+  `
+})
+```
+
+## Responsividade
+
+### Definir viewport (tamanho da tela)
+
+```typescript
+// Mobile
+mcp__playwright__set_viewport({
+  width: 320,
+  height: 568
+})
+
+// Tablet
+mcp__playwright__set_viewport({
+  width: 768,
+  height: 1024
+})
+
+// Desktop
+mcp__playwright__set_viewport({
+  width: 1920,
+  height: 1080
+})
+```
+
+### Testar responsividade completa
+
+```typescript
+// 1. Definir viewport mobile
+mcp__playwright__set_viewport({ width: 320, height: 568 })
+
+// 2. Capturar screenshot
+mcp__playwright__screenshot({ path: "./mobile.png" })
+
+// 3. Verificar se menu mobile está visível
+mcp__playwright__eval({
+  expression: `
+    const mobileMenu = document.querySelector('.mobile-menu');
+    return mobileMenu && getComputedStyle(mobileMenu).display !== 'none';
+  `
+})
+
+// 4. Mudar para desktop
+mcp__playwright__set_viewport({ width: 1920, height: 1080 })
+
+// 5. Verificar se menu desktop está visível
+mcp__playwright__eval({
+  expression: `
+    const desktopMenu = document.querySelector('.desktop-menu');
+    return desktopMenu && getComputedStyle(desktopMenu).display !== 'none';
+  `
+})
+```
+
+## Detecção de Problemas Visuais
+
+### Detectar sobreposições
+
+```typescript
+mcp__playwright__eval({
+  expression: `
+    function checkOverlaps() {
+      const elements = Array.from(document.querySelectorAll('body *'));
+      let overlaps = [];
+
+      for (let i = 0; i < elements.length; i++) {
+        const rect1 = elements[i].getBoundingClientRect();
+        if (rect1.width === 0 || rect1.height === 0) continue;
+
+        for (let j = i + 1; j < elements.length; j++) {
+          const rect2 = elements[j].getBoundingClientRect();
+          if (rect2.width === 0 || rect2.height === 0) continue;
+
+          // Check if rectangles overlap
+          const overlap = !(
+            rect1.right < rect2.left ||
+            rect1.left > rect2.right ||
+            rect1.bottom < rect2.top ||
+            rect1.top > rect2.bottom
+          );
+
+          if (overlap && !elements[i].contains(elements[j]) && !elements[j].contains(elements[i])) {
+            overlaps.push({
+              element1: elements[i].tagName + (elements[i].id ? '#' + elements[i].id : ''),
+              element2: elements[j].tagName + (elements[j].id ? '#' + elements[j].id : '')
+            });
+          }
+        }
+      }
+
+      return overlaps;
+    }
+    checkOverlaps();
+  `
+})
+```
+
+### Detectar barras de rolagem duplas
+
+```typescript
+mcp__playwright__eval({
+  expression: `
+    const scrollableElements = Array.from(document.querySelectorAll('*')).filter(el => {
+      const style = getComputedStyle(el);
+      return (
+        style.overflow === 'auto' ||
+        style.overflow === 'scroll' ||
+        style.overflowX === 'auto' ||
+        style.overflowX === 'scroll' ||
+        style.overflowY === 'auto' ||
+        style.overflowY === 'scroll'
+      );
+    });
+
+    return {
+      count: scrollableElements.length,
+      elements: scrollableElements.map(el => ({
+        tag: el.tagName,
+        id: el.id,
+        class: el.className
+      }))
+    };
+  `
+})
+```
+
+### Verificar elementos fora da viewport
+
+```typescript
+mcp__playwright__eval({
+  expression: `
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+
+    const elementsOutside = Array.from(document.querySelectorAll('body *')).filter(el => {
+      const rect = el.getBoundingClientRect();
+      return (
+        rect.right < 0 ||
+        rect.left > viewportWidth ||
+        rect.bottom < 0 ||
+        rect.top > viewportHeight
+      );
+    }).map(el => ({
+      tag: el.tagName,
+      id: el.id,
+      class: el.className,
+      position: el.getBoundingClientRect()
+    }));
+
+    return elementsOutside;
+  `
+})
+```
+
+## Acessibilidade
+
+### Verificar contraste de cores (WCAG)
+
+```typescript
+mcp__playwright__eval({
+  expression: `
+    function getLuminance(r, g, b) {
+      const [rs, gs, bs] = [r, g, b].map(c => {
+        c = c / 255;
+        return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+      });
+      return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+    }
+
+    function getContrastRatio(rgb1, rgb2) {
+      const l1 = getLuminance(...rgb1);
+      const l2 = getLuminance(...rgb2);
+      const lighter = Math.max(l1, l2);
+      const darker = Math.min(l1, l2);
+      return (lighter + 0.05) / (darker + 0.05);
+    }
+
+    function rgbStringToArray(rgb) {
+      const match = rgb.match(/rgb\\((\\d+),\\s*(\\d+),\\s*(\\d+)\\)/);
+      return match ? [parseInt(match[1]), parseInt(match[2]), parseInt(match[3])] : null;
+    }
+
+    const btn = document.querySelector('button');
+    const style = getComputedStyle(btn);
+    const fg = rgbStringToArray(style.color);
+    const bg = rgbStringToArray(style.backgroundColor);
+
+    if (fg && bg) {
+      const ratio = getContrastRatio(fg, bg);
+      return {
+        ratio: ratio.toFixed(2),
+        wcagAA: ratio >= 4.5,
+        wcagAAA: ratio >= 7
+      };
+    }
+    return { error: 'Could not parse colors' };
+  `
+})
+```
+
+### Verificar área mínima de toque (44x44px)
+
+```typescript
+mcp__playwright__eval({
+  expression: `
+    const interactiveElements = document.querySelectorAll('button, a, input, select, textarea');
+    const tooSmall = Array.from(interactiveElements).filter(el => {
+      const rect = el.getBoundingClientRect();
+      return rect.width < 44 || rect.height < 44;
+    }).map(el => ({
+      tag: el.tagName,
+      id: el.id,
+      width: el.getBoundingClientRect().width,
+      height: el.getBoundingClientRect().height
+    }));
+
+    return {
+      total: interactiveElements.length,
+      tooSmall: tooSmall.length,
+      details: tooSmall
+    };
+  `
+})
+```
+
+## Aguardar Condições
+
+### Aguardar elemento estar visível
+
+```typescript
+mcp__playwright__wait_for_selector({
+  selector: "#success-message",
+  state: "visible",
+  timeout: 5000
+})
+```
+
+### Aguardar elemento ser removido
+
+```typescript
+mcp__playwright__wait_for_selector({
+  selector: ".loading-spinner",
+  state: "detached",
+  timeout: 10000
+})
+```
+
+## Fluxo Completo: Teste de Formulário de Login
+
+```typescript
+// 1. Navegar para página
+mcp__playwright__navigate({ url: "http://localhost:3000/login" })
+
+// 2. Verificar elementos existem
+mcp__playwright__query_selector({ selector: "#email" })
+mcp__playwright__query_selector({ selector: "#password" })
+mcp__playwright__query_selector({ selector: "#btn-submit" })
+
+// 3. Capturar screenshot inicial
+mcp__playwright__screenshot({ path: "./login-initial.png" })
+
+// 4. Preencher formulário
+mcp__playwright__fill({ selector: "#email", value: "usuario@teste.com" })
+mcp__playwright__fill({ selector: "#password", value: "senha123" })
+
+// 5. Verificar botão está habilitado
+mcp__playwright__eval({
+  expression: "!document.querySelector('#btn-submit').disabled"
+})
+
+// 6. Clicar em submit
+mcp__playwright__click({ selector: "#btn-submit" })
+
+// 7. Aguardar navegação
+mcp__playwright__wait_for_url({ url: "/dashboard" })
+
+// 8. Capturar screenshot final
+mcp__playwright__screenshot({ path: "./login-success.png" })
+
+// 9. Verificar estética do formulário
+mcp__playwright__set_viewport({ width: 320, height: 568 })
+mcp__playwright__eval({
+  expression: `
+    const form = document.querySelector('form');
+    const style = getComputedStyle(form);
+    return {
+      centered: style.margin === 'auto' || style.justifyContent === 'center',
+      noOverflow: style.overflow !== 'scroll',
+      appropriatePadding: parseInt(style.padding) >= 16
+    };
+  `
+})
+```
+
+## Dicas e Boas Práticas
+
+### 1. Sempre usar timeouts apropriados
+- Operações rápidas (clicks): 5000ms
+- Navegação: 10000ms
+- Carregamento de dados: 15000ms
+
+### 2. Capturar screenshots em pontos-chave
+- Estado inicial
+- Após cada interação importante
+- Estados de erro
+- Estado final
+
+### 3. Testar em múltiplas resoluções
+- Mobile: 320x568, 375x667, 414x896
+- Tablet: 768x1024, 1024x768
+- Desktop: 1366x768, 1920x1080, 2560x1440
+
+### 4. Verificar estados interativos
+- Hover (não disponível via Playwright MCP, verificar CSS)
+- Active (verificar após click)
+- Focus (verificar após navegação por teclado)
+- Disabled (verificar propriedade)
+
+### 5. Documentar falhas com evidências
+- Sempre incluir screenshot quando teste falhar
+- Incluir valores esperados vs obtidos
+- Registrar seletor usado e resultado

package/docs/fluxo-mensagens.md

@@ -0,0 +1,180 @@
+# Fluxo de Mensagens entre Agentes
+
+## Notificações e Comunicação
+
+### 1. Orquestrador → Estrutura
+**Momento**: Primeira execução (quando `sincron-auto-state` não existe)
+**Mensagem**: Demanda do usuário
+**Ação**: Estrutura configura permissões
+
+---
+
+### 2. Estrutura → Gestor Projeto
+**Momento**: Após configurar permissões
+**Mensagem**: Demanda do usuário + configuração completa
+**Ação**: Gestor Projeto cria `sincron-auto-state` e inicia planejamento
+
+---
+
+### 3. Orquestrador → Gestor Projeto
+**Momento**: Quando `sincron-auto-state` já existe
+**Mensagem**: Demanda do usuário
+**Ação**: Gestor Projeto interpreta tipo de demanda
+
+---
+
+### 4. Gestor Projeto → Construtor
+**Momento**: Após Skill Gerenciar identificar próxima task
+**Ação prévia**: Gestor atualiza status da task de `pendente` para `em execução`
+**Mensagem**:
+```json
+{
+  "task_id": "task-001",
+  "name": "Nome da Task",
+  "description": "Descrição do que fazer",
+  "user_stories": ["..."],
+  "acceptance_criteria": ["..."],
+  "status": "em execução"
+}
+```
+**Ação**: Construtor implementa a task
+
+---
+
+### 5. Construtor → Avaliador
+**Momento**: Após concluir construção da task
+**Mensagem**:
+```json
+{
+  "task_id": "task-001",
+  "status": "ready_for_evaluation",
+  "files_changed": ["file1.js", "file2.html"],
+  "summary": "Resumo do que foi implementado"
+}
+```
+**Ação**: Avaliador inicia processo de avaliação
+
+---
+
+### 6a. Avaliador → Construtor (Task Rejeitada)
+**Momento**: Quando task não passa na avaliação
+**Mensagem**:
+```json
+{
+  "task_id": "task-001",
+  "status": "rejected",
+  "evaluation_number": 1,
+  "issues_found": [
+    {
+      "type": "functional | visual",
+      "severity": "critical | high | medium | low",
+      "description": "Descrição do problema",
+      "recommendation": "Como corrigir",
+      "related_criteria": "Critério não atendido"
+    }
+  ]
+}
+```
+**Ação**: Construtor corrige problemas e reenvia para Avaliador
+
+---
+
+### 6b. Avaliador → Gestor Projeto (Task Aprovada)
+**Momento**: Quando task passa em todos os critérios
+**Mensagem**:
+```json
+{
+  "task_id": "task-001",
+  "status": "approved",
+  "evaluation_number": 2,
+  "summary": "Task aprovada após 2 iterações"
+}
+```
+**Ação**:
+- Gestor Projeto atualiza status da task de `em execução` para `completo`
+- Identifica próxima task (por FIFO - ordem de criação)
+- Se houver próxima: atualiza para `em execução` e envia para Construtor
+- Se não houver: notifica Orquestrador
+
+---
+
+### 7. Gestor Projeto → Orquestrador
+**Momento**: Quando todas as tasks estão `completo`
+**Mensagem**:
+```json
+{
+  "status": "all_tasks_completed",
+  "total_tasks": 15,
+  "completed_tasks": 15,
+  "timestamp": "2026-01-26T18:30:00Z"
+}
+```
+**Ação**: Orquestrador compila relatório final
+
+---
+
+## Ciclo Completo de Uma Task
+
+```
+Gestor Projeto
+    ↓ (envia task)
+Construtor
+    ↓ (ready_for_evaluation)
+Avaliador
+    ↓
+    ├─ (rejected) → Construtor → (ready_for_evaluation) → Avaliador
+    └─ (approved) → Gestor Projeto
+                        ↓
+                   (atualiza para completo)
+                        ↓
+                   (pega próxima task ou notifica Orquestrador)
+```
+
+---
+
+## Estados e Transições
+
+### Task Status Flow
+```
+pendente
+    ↓
+(Gestor envia para Construtor)
+    ↓
+em execução
+    ↓
+(Construtor envia para Avaliador)
+    ↓
+    ├─ Avaliação: REJEITADA
+    │       ↓
+    │  (volta para Construtor)
+    │       ↓
+    │  (Construtor corrige)
+    │       ↓
+    │  (reenvia para Avaliador)
+    │       ↓
+    └─ Avaliação: APROVADA
+            ↓
+       (notifica Gestor)
+            ↓
+        completo
+```
+
+---
+
+## Responsabilidades de Atualização
+
+| Arquivo | Quem Cria | Quem Atualiza | Quando Atualiza |
+|---------|-----------|---------------|-----------------|
+| `sincron-auto-state` | Gestor Projeto | Gestor Projeto | - Ao criar tasks (Skill Projetar)<br>- `pendente` → `em execução` (ao enviar para Construtor)<br>- `em execução` → `completo` (após aprovação do Avaliador) |
+| `relatorio-avaliacao.json` | Avaliador | Avaliador | - A cada avaliação (aprovada ou rejeitada)<br>- Incrementa evaluation_number em reavaliações |
+| `settings.local.json` | Estrutura | Estrutura | - Uma única vez na configuração inicial |
+| `reports/relatorio-*.md` | Orquestrador | Orquestrador | - Ao finalizar todas as tasks do projeto |
+
+---
+
+## Perguntas em Aberto
+
+1. O Construtor notifica alguém quando inicia a construção?
+2. Há timeout para construção/avaliação?
+3. Como lidar com erros/crashes de um agente?
+4. Sistema deve ter logs de todas as comunicações?