ganbatte-os 0.2.37 → 0.2.41

package/.gos/libraries/ui-guardrails-checklist.md

@@ -0,0 +1,144 @@
+# UI Guardrails Checklist (detalhe)
+
+> Detalhe expandido de cada item do `ui-guardrails`. Consultar quando uma violacao precisar ser explicada ao usuario.
+
+## A — Estados visuais
+
+### A1 — Loading
+- Tela inteira: skeleton com a estrutura visual (header skeleton, lista de cards skeleton).
+- Componente isolado (ex: botao salvando): spinner inline ou disabled state.
+- Anti-padrao: tela em branco enquanto carrega.
+
+Codegen exige no plan:
+```markdown
+### Estado: loading
+- Skeleton: 3 cards 240x80px com bg-muted-foreground/10 + shimmer.
+- Trigger: query.isPending
+- Duracao max: 3s antes de error.
+```
+
+### A2 — Empty
+- Copy explicando POR QUE esta vazio.
+- Ilustracao OU icone grande.
+- CTA primario para sair do empty (criar item, importar, etc.).
+- Anti-padrao: "Nenhum dado" sem nada mais.
+
+Codegen exige:
+```markdown
+### Estado: empty
+- Copy: "Voce ainda nao tem nenhum projeto. Comece criando um."
+- Icone: FolderPlus 48px text-muted-foreground.
+- CTA: "Criar primeiro projeto" (Button variant=primary).
+```
+
+### A3 — Error
+- Mensagem clara (nao "erro 500").
+- Acao de recovery (tentar de novo, voltar, contato).
+- Distincao: erro recuperavel vs nao-recuperavel.
+
+```markdown
+### Estado: error
+- Tipo recuperavel: toast variant=error + retry inline.
+- Tipo nao-recuperavel: tela full com copy + CTA voltar.
+```
+
+### A4 — Success (quando aplicavel)
+- Toast inline ou success state pos-form.
+- Auto-dismiss em 3-5s OU acao explicita do usuario.
+
+### A5 — Default
+- Estado normal, dados presentes.
+
+## B — Responsividade
+
+### Breakpoints obrigatorios
+- Mobile: <768px (preferencia: comeca daqui — mobile-first).
+- Tablet: 768-1024px.
+- Desktop: 1024-1920px.
+
+### Comportamentos esperados
+- Sidebar -> drawer no mobile.
+- Tabela -> cards no mobile.
+- Drawer right -> bottom sheet no mobile.
+- Tipografia escala (text-base mobile, text-lg desktop ou similar).
+
+### Codegen exige no plan
+```markdown
+### Responsividade
+- Mobile: lista vira cards verticais empilhados, sem hover.
+- Tablet: 2 colunas de cards.
+- Desktop: tabela tradicional com hover.
+```
+
+## C — Acessibilidade
+
+### Roles ARIA
+- `<button>` para acao -> nao usar `<div onClick>`.
+- `<dialog>` ou `role="dialog"` + aria-labelledby para modals.
+- `role="listbox"` + `role="option"` em selects custom.
+
+### Labels
+- Input sem `<label>` visivel: usar `aria-label`.
+- Icon-only button: `aria-label="Fechar"` obrigatorio.
+
+### Focus
+- Modal aberto: focus vai para primeiro elemento focavel.
+- Modal fechado: focus volta para trigger.
+- Tab order segue ordem visual.
+- Focus indicator distinto de hover (outline 2px ring-primary).
+
+### Contraste
+- AA: 4.5:1 texto, 3:1 UI.
+- Erro inline NAO so vermelho — adicionar icone/texto "Erro:".
+
+## D — Tokens do DS
+
+### Cores
+- OK: `bg-primary`, `text-foreground`, `border-border`.
+- Anti: `bg-[#3b82f6]`, `text-blue-500` quando primary existe.
+
+### Spacing
+- OK: `gap-2`, `p-4`, `mt-6`.
+- Anti: `gap-[7px]`, `p-[13px]`.
+
+### Typography
+- OK: `text-sm`, `font-semibold`, `leading-tight`.
+- Anti: `text-[13px]`, `tracking-[0.02em]` quando token existe.
+
+### Radius
+- OK: `rounded`, `rounded-md`, `rounded-lg`.
+- Anti: `rounded-[7px]`.
+
+### Excecoes permitidas (com justificativa)
+- Animacao especifica nao-mapeada: `[animation-delay:120ms]` OK.
+- Posicionamento dinamico: `top-[calc(100%+8px)]` OK.
+
+## E — Interacao
+
+### Trigger declaration
+Cada elemento interativo precisa:
+- Trigger: o que dispara (click, hover, focus, keypress, mount, query)
+- Acao: que callback/mutation roda
+- Resultado: qual estado muda + UI feedback
+
+### Edge cases obrigatorios
+- Double-click rapido em CTA -> debounce 300ms ou disabled durante mutation.
+- Mutation lenta (>3s) -> mostrar loading inline ou progress.
+- Mutation falha -> rollback ou error state com retry.
+- Concorrencia (2 usuarios editando) -> conflict resolution declarado.
+
+## Self-check rapido
+
+Antes de submeter tela para codegen:
+
+```
+[ ] A1 loading state declarado e visualmente coerente?
+[ ] A2 empty state existe + CTA primaria?
+[ ] A3 error state com recovery?
+[ ] B responsividade nos 3 breakpoints?
+[ ] C aria-label em icon buttons + focus visivel?
+[ ] D 0 valores hardcoded fora do DS?
+[ ] E todos os triggers tem acao + resultado + edge cases?
+```
+
+Falhou em algum -> NAO codar ainda. Volte ao plano.

package/.gos/libraries/visual-diff-lenses.md

@@ -0,0 +1,114 @@
+# Visual Diff Lenses
+
+> Referencia das 6 lenses usadas por `figma-print-diff` e `audit-screenshots`. Inspirado em Nielsen Heuristics + design-critique (uxdudu) + WCAG.
+
+## Lens 1 — Layout & hierarquia
+
+Pergunta-mestra: "A estrutura espacial bate?"
+
+Sub-checks:
+- Containers principais (sidebar, header, footer, main) presentes em ambos?
+- Ordem de filhos dentro de cada container coincide?
+- Proporcoes (sidebar 240px, main 1fr) coerentes?
+- Densidade visual (cards/lista) similar?
+
+Severity guide:
+- high: container ausente/extra
+- medium: ordem trocada
+- low: proporcao 10-20% diferente
+
+## Lens 2 — Tokens visuais
+
+Pergunta-mestra: "Cor, tipo, espacamento batem com o DS?"
+
+Sub-checks:
+- Cor de background dos blocos
+- Cor de texto (primary, secondary, muted)
+- Borders e radius
+- Tipografia (family, size, weight, line-height)
+- Spacing (padding/margin/gap)
+- Shadows e elevations
+
+Severity guide:
+- high: cor de acao primaria errada
+- medium: spacing 2x diferente
+- low: radius cosmetico
+
+## Lens 3 — Estados
+
+Pergunta-mestra: "Todos os estados estao implementados?"
+
+Sub-checks:
+- Loading (skeleton, spinner)
+- Empty (placeholder, CTA)
+- Error (mensagem, recovery)
+- Success (toast, inline)
+- Hover/Focus/Active
+- Disabled
+
+Severity guide:
+- high: empty/error nao implementado
+- medium: hover sem feedback
+- low: focus ring cosmetico
+
+## Lens 4 — Conteudo
+
+Pergunta-mestra: "Textos e visuais coincidem?"
+
+Sub-checks:
+- Textos literais (sem inventar traducao)
+- Icones (mesma lib, mesma variante)
+- Imagens (placeholder vs real)
+- Dados mockados (formato, plausibilidade)
+
+Severity guide:
+- high: copy errada que altera significado
+- medium: icone trocado
+- low: lorem ipsum esquecido
+
+## Lens 5 — Interacao (inferida do estatico)
+
+Pergunta-mestra: "Affordances batem?"
+
+Sub-checks:
+- Cursor pointer onde Figma mostra elemento "clicavel"
+- Botoes com aparencia de botao (nao texto plano)
+- Inputs com aparencia de input (border, placeholder)
+- Tooltips/popovers posicionados corretamente quando visiveis
+
+Severity guide:
+- high: botao primario sem aparencia de botao
+- medium: link disfarcado de texto
+- low: cursor em element nao-clicavel
+
+## Lens 6 — Acessibilidade visual
+
+Pergunta-mestra: "Acessivel ao olhar?"
+
+Sub-checks:
+- Contraste AA (4.5:1 texto, 3:1 UI components)
+- Toque minimo 44x44px em mobile
+- Focus indicator distinto de hover
+- Texto sem so cor (icone + cor para indicar erro)
+
+Severity guide:
+- high: contraste reprovado em texto principal
+- medium: toque <44px em mobile
+- low: focus mesmo cor que hover
+
+## Composicao das lenses
+
+Ordem fixa: 1 -> 2 -> 3 -> 4 -> 5 -> 6.
+
+Por que essa ordem?
+- Layout antes de token (sem layout, token nao importa).
+- Token antes de estado (estado depende de tokens corretos).
+- Estado antes de conteudo (conteudo so faz sentido com estado completo).
+- Interacao depois de conteudo (precisa ver afford).
+- A11y por ultimo (gate final).
+
+## Anti-patterns
+
+- Pular lens 3: time esquece estados, codegen sai sem loading/empty/error.
+- Inverter 1 e 2: comeca medindo cor e nao percebe que falta sidebar inteira.
+- Severity hyperinflation: tudo high -> nada e high.

package/.gos/playbooks/audit-streaming-playbook.md

@@ -0,0 +1,86 @@
+# Playbook — Auditoria visual streaming (audit-screenshots)
+
+Guia de uso do fluxo de correção visual **plano-primeiro, task-por-insumo**. Confronta o app implementado
+contra o Figma e gera UM plano de correção com tasks escritas na hora — cada divergência passa pelo gate
+de reuso de componente (reuse / create / merge). Substitui o modelo antigo de fila (acumular prints →
+materializar no `close`).
+
+## Quando usar
+
+- Você tem N telas com divergências visuais (cola prints, ou aponta rotas) e quer UM plano de fix.
+- Quer auditar sistematicamente um tipo de tela contra o Figma (`validate`).
+- NÃO use para planejar tela nova (use `*plan` / plan-blueprint) nem para executar (use `*execute-plan`).
+
+## Pré-requisitos do workspace
+
+1. `.gos-local/plan-paths.json` configurado (campo `figma_screen_map`; default `docs/figma-screen-map.md`).
+2. `docs/figma-screen-map.md` — mapa canônico `Rota app ↔ node-id` (contrato tela↔Figma do projeto).
+3. **Figma MCP** ativo (expected) e **Playwright** disponível (actual, captura do app vivo).
+4. `progress.txt` na raiz (criado no primeiro `*plan`/`open`).
+
+## Fluxo end-to-end
+
+### 1. Abrir o plano (uma vez por auditoria)
+
+```
+*audit-screenshots open [SLUG]
+```
+
+Cria `docs/plans/PLAN-NNN-fix-<SLUG>/` com `plan.md` em **`status: aberto`** (draft) + `context.md` +
+`tasks/` vazio + `audit-evidence/`. **Não** roda check-plan (o plano ainda é rascunho).
+
+### 2. Adicionar insumos (quantos quiser, a qualquer momento)
+
+```
+# Cole o print + contexto, OU aponte a rota para o Playwright capturar:
+*audit-screenshots add   "a aba negocios esta sem a coluna Area"   # + imagem colada
+*audit-screenshots add   /dashboard/projetos/123?tab=negocios       # captura via Playwright
+```
+
+Cada insumo, NA HORA: resolve tela no mapa → captura actual (print ou Playwright) → pull Figma (MCP) →
+confronta via `figma-print-diff` (single-pass, lenses 1-6) → **gate de reuso** por divergência estrutural
+→ escreve `tasks/T-NN-*.md` (`status: pendente`) com evidência anexada. Sem fila, sem `close` no fim.
+
+### 3. (Opcional) Sweep de validação por tipo de tela
+
+```
+*audit-screenshots validate listagem      # todas as telas tipo "listagem" no mapa
+*audit-screenshots validate --all          # varre o mapa inteiro
+```
+
+Itera o `figma-screen-map.md`, captura Playwright + pull Figma, confronta e escreve tasks — mesmo fluxo do `add`.
+
+### 4. Revisar e finalizar
+
+```
+*audit-screenshots list        # tasks escritas ate agora + decisoes de componente
+*audit-screenshots finalize    # flip status: pendente -> roda check-plan.js -> pronto p/ execute-plan
+```
+
+`finalize` valida que cada task é self-contained, vira o plano para `status: pendente`, dispara
+`ui-guardrails` e roda `check-plan.js` (gate determinístico). Exit 0 → o plano é input de `*execute-plan`.
+
+```
+*execute-plan PLAN-NNN-fix-<SLUG>
+```
+
+`*audit-screenshots discard` aborta o plano aberto a qualquer momento.
+
+## Gate de reuso de componente (design-to-code)
+
+Cada divergência em estrutura reusável (table, card, form, list…) NÃO vira patch one-off. O fluxo mapeia o
+elemento → checa a biblioteca (`component-dedup`) → decide **reuse | create | merge** (ver
+`libraries/component-reuse-gate.md`). A task grava `component_decision` + `component_target`.
+
+**Exemplo (Fractus):** divergência numa tabela → a primitiva `DataTable` (TanStack) já existe →
+decisão **reuse**. A correção é nas `columns`/dados daquela tela OU na própria primitiva (se o defeito é
+compartilhado) — nunca um `<table>` novo. `negocios-table`, `funders-table` etc. = 1 primitiva, N usos.
+
+## Por que mudou (vs modelo de fila)
+
+| Antes (fila) | Agora (streaming) |
+|--------------|-------------------|
+| `add` acumula em `audit-session.json` | `open` cria plano draft; o diretório É o estado |
+| Tasks só nascem no `close` (perda de contexto) | Task escrita NA HORA, por insumo, com evidência |
+| Correção = patch da tela | Correção passa pelo gate de reuso (reuse/create/merge) |
+| check-plan no `close` | check-plan só no `finalize` (plano `aberto` é estado válido) |

package/.gos/skills/adr-tech-decisions/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: adr-tech-decisions
+description: >
+  Decide stack tecnico de um PRD interativamente, com KB embutido de Cloudflare (Workers,
+  Pages, D1, R2, KV, DO, Realtime via WebSocket) e Supabase (Auth, Postgres, Realtime).
+  SEMPRE pergunta ao usuario as decisoes-chave antes de chumbar — MVPs descartaveis tem
+  estrategia diferente de produtos continuos. Output: docs/adr/ADR-NNN-<slug>.md.
+argument-hint: "<PRD-id> [--cloudflare-only] [--with-supabase] [--websocket]"
+allowedTools: [Read, Glob, Grep, Bash, Write, Edit, AskUserQuestion]
+sourceDocs:
+  - libraries/cloudflare-stack-kb.md
+  - libraries/supabase-stack-kb.md
+  - templates/adr-tmpl.yaml
+use-when:
+  - tem-se PRD pronto e precisa decidir arquitetura
+  - antes de plan-blueprint quando o projeto e novo
+  - quando ha duvida entre Cloudflare-only vs hibrido com Supabase
+do-not-use-for:
+  - projetos que ja tem stack.md definido (use plan-blueprint direto)
+  - mudanca pontual de lib (registrar via comment no plan)
+metadata:
+  category: architecture
+---
+
+Voce esta executando como **Arquiteto Pragmatico** via skill `adr-tech-decisions`. Le PRD, faz 5-7 perguntas direcionadas ao usuario (todas em PT-BR, sem jargao quando possivel), consulta KB embutido e produz ADR + stack.md compatibilizado com plan-blueprint.
+
+## Contrato
+
+1. Input obrigatorio: `PRD-id`. Resolver `docs/prd/<PRD-id>/prd.md`. Ausente -> abortar.
+2. Ler `descartavel` do frontmatter PRD — afeta perfil de decisoes (ver matriz).
+3. SEMPRE perguntar ao usuario antes de fechar (regra do dono do framework: `SEMPRE pergunte ao usuario`).
+4. Output: `docs/adr/ADR-NNN-<slug>.md` + `docs/stack.md` (criar ou atualizar).
+5. Apos ADR: `docs/stack.md` fica disponivel para `plan-blueprint` consumir.
+
+## Matriz de decisao por perfil
+
+### Perfil A — Descartavel (uso unico, vida util semanas)
+
+Default proposto (nao chumbar — pergunte):
+- Frontend: Vite + React + TypeScript + Tailwind + shadcn/ui
+- Hosting: Cloudflare Pages (free, deploy via git)
+- Backend: NENHUM (somente front, dados em localStorage ou Cloudflare KV se publico)
+- Auth: nenhuma OU Cloudflare Access (free para 50 users, sem codigo)
+- Realtime: nenhum
+- DB: nenhum OU Cloudflare KV (free 100k reads/dia)
+
+### Perfil B — Continuo, simples (CRUD basico, ate 1k users)
+
+Default proposto:
+- Frontend: Vite + React + TS + Tailwind + shadcn/ui em Cloudflare Pages
+- Backend: Cloudflare Workers (free 100k reqs/dia)
+- DB: Cloudflare D1 (free 5GB) OU Supabase Postgres (free 500MB)
+- Auth: Supabase Auth (free 50k MAU)
+- Realtime: nenhum
+- Storage: Cloudflare R2 (free 10GB)
+
+### Perfil C — Continuo, realtime (chat, dashboard ao vivo, jogo)
+
+Default proposto:
+- Frontend: idem perfil B
+- Backend: Cloudflare Workers + Durable Objects (free 1M ops/dia) — para WebSocket
+- Realtime: WebSocket via DO (sem servidor separado)
+- DB: Supabase Postgres + Realtime (channels via Postgres logical replication)
+- Auth: Supabase Auth
+
+## Perguntas obrigatorias (ordem)
+
+Sempre perguntar via `AskUserQuestion`:
+
+1. "Esse produto e pra usar uma vez ou rodar continuo?" -> define perfil A vs B/C.
+2. "Vai precisar de login? (sim/nao/talvez)" -> define auth.
+3. "Vai ter dados que mudam ao vivo (chat, notificacao em tempo real)?" -> define realtime.
+4. "Tem orcamento mensal pra infra ou precisa caber 100% no free tier?" -> define limites.
+5. "Algum lock-in que voce QUER ter ou EVITAR? (ex: ja uso Supabase no outro projeto)" -> overrides.
+6. (Se perfil C) "Quantos usuarios simultaneos voce espera ter conectados ao mesmo tempo?" -> dimensiona DO.
+7. "Quer separar frontend e backend em projetos diferentes ou monolito?" -> define repo strategy.
+
+## Pre-flight
+
+1. Verificar se KB esta disponivel: `libraries/cloudflare-stack-kb.md` e `libraries/supabase-stack-kb.md`. Se ausentes, abortar com instrucao para rodar setup do G-OS.
+2. Resolver `dirs.adr` via `.gos-local/plan-paths.json` (default: `docs/adr/`).
+
+## Output (ADR-NNN-<slug>.md)
+
+Use template `templates/adr-tmpl.yaml` mas exporta como markdown:
+
+```markdown
+# ADR-NNN: <decisao principal>
+
+**Status**: accepted
+**Date**: <iso>
+**PRD**: PRD-NNN-<slug>
+**Perfil**: A (descartavel) | B (continuo simples) | C (realtime)
+
+## Contexto
+<2-3 paragrafos, citando trechos do PRD que motivam>
+
+## Decisoes (resumo executivo)
+
+| Camada | Escolha | Alternativa rejeitada | Motivo |
+|--------|---------|----------------------|--------|
+| Frontend | Vite + React + TS + Tailwind + shadcn | Next.js | <motivo> |
+| Hosting | Cloudflare Pages | Vercel | <motivo> |
+| Backend | Cloudflare Workers | Express+VPS | <motivo> |
+| DB | <D1\|Supabase\|nenhum> | <alternativa> | <motivo> |
+| Auth | <opcao> | <alternativa> | <motivo> |
+| Realtime | <DO+WS\|Supabase Realtime\|nenhum> | <alternativa> | <motivo> |
+
+## Constraints respeitados
+- Free tier: <lista de limites e como ficamos abaixo deles>
+- Descartavel: <true/false> -> <decisoes simplificadas tomadas>
+
+## Consequencias
+- (+) <positivas>
+- (-) <negativas>
+- (~) <neutras>
+
+## Proximo passo
+- Atualizar `docs/stack.md` (ja feito automaticamente).
+- Rodar `*plan-blueprint <tela>` para primeira tela.
+```
+
+## Saida secundaria (docs/stack.md)
+
+Atualizar/criar stack.md com formato compativel com `plan-blueprint`:
+
+```markdown
+# Stack do projeto
+
+## Frontend
+- Framework: <Vite + React + TS>
+- Styling: Tailwind v4 + shadcn/ui + tv()
+- State: <local|zustand|jotai>
+- Data fetching: <fetch|swr|tanstack-query>
+
+## Backend
+- Runtime: <Cloudflare Workers|nenhum>
+- DB: <D1|Supabase Postgres|nenhum>
+- Auth: <opcao>
+- Realtime: <opcao>
+
+## Hosting
+- Frontend: Cloudflare Pages
+- Backend: <Cloudflare Workers|N/A>
+
+## Bindings (Cloudflare)
+- D1: <DB_NAME> (se aplicavel)
+- KV: <NAMESPACE> (se aplicavel)
+- R2: <BUCKET> (se aplicavel)
+- DO: <CLASS_NAME> (se aplicavel)
+
+## Decisoes-chave (refs ADRs)
+- ADR-NNN: <decisao>
+```
+
+## Regras criticas
+
+- **NUNCA chumbar tecnologia sem perguntar**. Mesmo que o perfil indique padrao, perguntar ao usuario antes de escrever ADR.
+- **Free tier first**: para descartaveis, recusar opcoes pagas mesmo que tecnicamente melhores.
+- **Linkar com plan-blueprint**: o `arch_change` flag dele depende do stack.md gerado aqui.
+- **Anti-overengineer**: para perfil A, recusar microservicos, kubernetes, message queues, observability stack — limite e localStorage + fetch.
+- **Citar KB**: ao recomendar uma tecnologia, citar limite especifico do KB ("Workers free = 100k reqs/dia, suficiente para 1k users ativos").
+
+## Input
+
+$ARGUMENTS