ganbatte-os 0.2.37 → 0.2.41

package/.gos/skills/ui-guardrails/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: ui-guardrails
+description: >
+  Pre-flight obrigatorio antes de codar uma tela. Verifica que cada task de tela tem
+  estados (loading/empty/error/success), responsividade, a11y e tokens declarados.
+  Bloqueia codegen se faltar — evita que erros de UI sejam descobertos tarde.
+  Pensado para reduzir o "trabalho extra de corrigir o que nao foi previsto".
+argument-hint: "<plan-id-ou-task-path>"
+allowedTools: [Read, Glob, Grep, Edit, AskUserQuestion]
+sourceDocs:
+  - libraries/ui-guardrails-checklist.md
+use-when:
+  - antes de design-to-code/figma-implement-design rodar
+  - validar plano de UI antes de execute-plan
+  - usuario reclama "esqueceram do estado vazio de novo"
+do-not-use-for:
+  - tasks de backend (sem UI)
+  - bug fixes pontuais (use react-doctor)
+metadata:
+  category: validation
+---
+
+Voce esta executando como **UI Guardrails Validator** via skill `ui-guardrails`. Verifica que cada task de UI tem cobertura completa antes de codegen — bloqueia execucao se faltar.
+
+## Contrato
+
+1. Le um plano (`docs/plans/PLAN-NNN/`) ou task individual (`tasks/T-NN-...md`).
+2. Para cada task com `area: ui-ux` ou `area: frontend`, aplica checklist (ver `libraries/ui-guardrails-checklist.md`).
+3. Se faltar item -> output structured com gaps + sugestao de adicao + opcao de `AskUserQuestion` para corrigir inline OU abortar.
+4. Se passar -> output curto "OK, N tasks validadas, codegen liberado".
+
+## Checklist (resumo — detalhe na library)
+
+Para CADA task de UI:
+
+### A. Estados visuais (5 obrigatorios)
+- [ ] Loading: **skeleton OBRIGATORIO** (shadcn `Skeleton`) para listas/cards/tabelas; spinner Lucide `Loader2` so para botoes ou acoes pontuais.
+- [ ] Empty: copy + Lucide icon (h-12 w-12 text-muted-foreground) + CTA primario.
+- [ ] Error: mensagem + Lucide `AlertTriangle` + recovery action (botao retry).
+- [ ] Success (quando aplicavel): Lucide `CheckCircle2` em toast/inline.
+- [ ] Default (renderizado normal).
+
+**Regra critica**: **SEMPRE skeleton ao carregar dados**, **SEMPRE empty state quando lista vazia**. Sem excecoes mesmo em descartavel.
+
+### B. Responsividade (3 breakpoints minimos)
+- [ ] Mobile (<768px): layout declarado
+- [ ] Tablet (768-1024px): comportamento declarado
+- [ ] Desktop (>1024px): default
+
+### C. A11y (4 minimos)
+- [ ] Roles ARIA quando aplicavel (button, dialog, listbox)
+- [ ] Labels em inputs (htmlFor + id ou aria-label)
+- [ ] Focus order definido se mais de 3 elementos interativos
+- [ ] Contraste AA verificado (lens 6 do figma-print-diff)
+
+### D. Tokens do DS (todos via referencia)
+- [ ] Cores via tokens (`bg-primary`, NUNCA hex direto)
+- [ ] Spacing via scale (`gap-4`, NUNCA `gap-[17px]`)
+- [ ] Typography via classes (`text-base`, NUNCA `text-[15px]`)
+- [ ] Border-radius via scale (`rounded-md`, NUNCA `rounded-[7px]`)
+
+### F. Lucide React (zero-emoji policy)
+- [ ] Import de icones SO de `lucide-react` (nunca FontAwesome/Heroicons/outra lib).
+- [ ] **Zero emoji unicode em strings de UI** (regex `/[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}]/u`).
+- [ ] Icon-only button com `aria-label` obrigatorio.
+- [ ] Tamanhos canonicos: `h-3.5 w-3.5` inline, `h-4 w-4` button, `h-5 w-5` heading, `h-12 w-12` empty state, `h-16 w-16` hero.
+
+Detalhe: `libraries/lucide-icons-policy.md`.
+
+### E. Interacao (quando aplicavel)
+- [ ] Trigger -> acao -> resultado declarado em `## Interacoes & Estados`
+- [ ] Edge case: o que acontece se trigger duplicar (debounce)?
+- [ ] Edge case: o que acontece se backend demorar >3s?
+
+## Niveis de violacao
+
+| Tipo | Severidade | Acao |
+|------|-----------|------|
+| A faltando (estado) | high | Bloqueia codegen. Pede correcao via AskUserQuestion. |
+| B faltando (responsivo) | high | Bloqueia se task e tela full. Warning se componente isolado. |
+| C faltando (a11y) | medium | Warning. Codegen continua mas adiciona TODO no codigo. |
+| D faltando (tokens) | medium | Warning. Codegen pode prosseguir mas relatorio ao final. |
+| E faltando (interacao) | high (se ha trigger) | Bloqueia. plan-blueprint ja exige isso — caso aqui e detectar regressao. |
+| F faltando (Lucide/emoji) | high | Bloqueia. Recusar codigo com emoji em UI ou icone nao-Lucide. |
+
+## Output
+
+```
+[ui-guardrails] PLAN-NNN — N tasks de UI validadas
+
+[OK]   T-01: cards-projeto-list           A B C D E
+[FAIL] T-02: drawer-edit-projeto          A . C D E   (faltando: empty state, hover focus)
+[WARN] T-03: tooltip-status               A B . D E   (a11y: sem aria-label)
+
+bloqueado: 1 task (T-02). Corrija antes de design-to-code.
+warnings: 1 (T-03 — a11y).
+```
+
+## Hook em pipeline
+
+`prototype-orchestrator` (fase 5 -> 6) e `plan-blueprint` (apos plan-to-tasks) DEVEM chamar `ui-guardrails` automaticamente em produtos NAO-descartaveis. Para descartaveis, oferecer skip via flag `--no-guardrails`.
+
+## Regras criticas
+
+- **Descartavel relax**: se plan tem `descartavel: true` no frontmatter, A/B viram warning (nao block).
+- **Codegen sem guardrails**: violacao da regra do dono ("muito trabalho corrigindo erros nao previstos"). Bloqueia.
+- **Self-update**: se task tem `interaction_target` mas falta `## Interacoes & Estados` no plano, sugerir patch automatico.
+
+## Input
+
+$ARGUMENTS

package/.gos/templates/intakeTemplate.md

@@ -0,0 +1,41 @@
+---
+intake_id: INTAKE-<NNN>-<slug>
+status: pronto-para-prd
+descartavel: <true|false>
+created_at: <iso>
+---
+
+# <Titulo curto da ideia>
+
+## Problema (em uma frase)
+<sintese feita pelo agente>
+
+## Historias reais coletadas
+- <bullet 1>
+- <bullet 2>
+
+## Persona
+<descricao em prosa, contexto incluido>
+
+## Jobs-to-be-done
+- Quando <situacao>, eu quero <acao>, para que <resultado>.
+
+## Limites (o que NAO fazer)
+- <bullet>
+
+## Telas-chave (visao bruta)
+1. <tela 1 — descricao em palavras leigas>
+2. <tela 2>
+
+## Inspiracoes
+- <link ou nome>
+
+## Escopo
+- Descartavel: <sim|nao>
+- Vida util esperada: <uma vez|semanas|meses|continuo>
+
+## Metrica de sucesso (linguagem humana)
+<frase do usuario>
+
+## Proximo passo
+- Rodar `*prd-from-intake INTAKE-<NNN>-<slug>` para gerar PRD lean.

package/.gos/templates/planTemplate.md

@@ -15,7 +15,13 @@ validated_at: null
 
 # <Título da tela>
 
-## Contexto
+> **Modelo O QUE / ONDE / COMO / POR QUE** — este plano (e cada task que ele gera) responde às 4 perguntas:
+> - **POR QUE** → `## Contexto` (motivação, PRD/ticket, problema).
+> - **O QUE** → `## Componentes mapeados` + `## Interações & Estados` + `## Checklist de aceite` (o entregável).
+> - **ONDE** → `context.md` (`## Arquivos relevantes`) + coluna de paths nas tasks (`## Arquivos`).
+> - **COMO** → `## Aderência à Stack` + `## Plano de execução` (abordagem técnica, fetching, composição).
+
+## Contexto (POR QUE)
 
 <Por que esta tela existe — referência ao PRD, ticket, decisão de produto.>
 
@@ -140,10 +146,11 @@ Decisões possíveis:
 > Gaps detectados confrontando Postman/regras-de-negocio com a necessidade da tela. Cada item vira task ClickUp atribuída ao Douglas (default) ou ao `ASSIGNEE` informado. Vazio = backend completo para esta tela.
 
 > Coluna `Bloqueia tasks` lista os T-IDs frontend cujo frontmatter declara `depends_on_backend:` apontando para a `gap-key` desta linha (ex.: `migration-20260501150000`).
+> Coluna `Bypass frontend` declara COMO o frontend entrega sem o backend pronto (fallback, mock, toast "em breve", cast + null-coalesce). Sem bypass declarado, a tarefa frontend fica `bloqueada-backend`. **Princípio: frontend nunca bloqueado por gap de backend — sempre há bypass OU a task é explicitamente bloqueada.**
 
-| gap-key | Gap | Endpoint/Coleção esperada | ClickUp ID | Status | Bloqueia tasks |
-|---------|-----|---------------------------|------------|--------|----------------|
-|         |     |                           |            |        |                |
+| gap-key | Gap | Bypass frontend | Endpoint/Coleção esperada | ClickUp ID | Status | Bloqueia tasks |
+|---------|-----|-----------------|---------------------------|------------|--------|----------------|
+|         |     |                 |                           |            |        |                |
 
 ## Mock strategy
 
@@ -157,6 +164,20 @@ Decisões possíveis:
 - **Postman**: `<lista de coleções/endpoints relevantes em docs/postman/>`
 - **Stack ref**: `<sha de stack.md>`
 
+## Tabela de regressão
+
+> Fluxos/telas existentes que este plano NÃO pode quebrar. `validate-plan` confere que nenhum item regrediu. Vazio = plano greenfield sem superfície a preservar.
+
+- <rota/fluxo 1 — o que deve continuar funcionando (fetching + markup preservados)>
+- <rota/fluxo 2>
+
+## Anti-padrões
+
+> Proibições explícitas desta entrega. O executor recusa qualquer task que viole. Derivado das memórias do projeto + decisões deste plano.
+
+- ❌ <ação proibida 1 — ex.: criar primitiva nova quando componente X já cobre; estender via prop>
+- ❌ <ação proibida 2 — ex.: hardcode de RBAC inline em JSX; centralizar em helper>
+
 ## Riscos & Rollback
 
 - <risco>

package/.gos/templates/prdLeanTemplate.md

@@ -0,0 +1,40 @@
+---
+prd_id: PRD-<NNN>-<slug>
+intake_ref: INTAKE-<NNN>-<slug>
+descartavel: <bool>
+status: pronto-para-adr
+created_at: <iso>
+---
+
+# <Titulo>
+
+## TL;DR (1 paragrafo, max 4 linhas)
+<problema + persona + solucao + metrica>
+
+## Quem usa
+<persona em 2 linhas>
+
+## Por que existe
+<problema em 2 linhas, citando 1 historia real>
+
+## O que faz (3-7 bullets)
+- <feature 1>
+- <feature 2>
+
+## Telas-chave
+| # | Tela | Proposito | Inputs | Outputs |
+|---|------|-----------|--------|---------|
+| 1 | <nome> | <verbo + objeto> | <dado entrada> | <dado saida> |
+
+## Criterios de aceite (do nao-tecnico)
+- [ ] Usuario consegue <acao primaria> em menos de <X> passos
+- [ ] <criterio mensurivel>
+
+## Metrica de sucesso
+<copia da metrica humana + 1 metrica quantitativa derivada>
+
+## NAO faz parte (escopo negativo)
+- <bullet>
+
+## Proximo passo
+- Rodar `*adr-tech-decisions PRD-<NNN>-<slug>` para definir arquitetura.

package/.gos/templates/taskTemplate.md

@@ -17,15 +17,39 @@ assignees: []
 links: []
 ---
 
-## Contexto
+<!--
+MODELO DE TASK: toda task DEVE responder às 4 perguntas, nesta ordem:
+  POR QUE → ## Contexto
+  O QUE   → ## Objetivo + ## Entrega
+  ONDE    → ## Arquivos
+  COMO    → ## Plano de execução
+Nenhuma seção pode ficar com placeholder. Se não há resposta para uma das 4, a task não está pronta para execução.
+-->
 
-<Por que esta task existe — referência direta ao plano pai e ao critério de aceite.>
+## Contexto (POR QUE)
 
-## Objetivo
+<Por que esta task existe — referência direta ao plano pai e ao critério de aceite. Qual problema/gap motiva.>
 
-<Resultado esperado em 1-2 frases.>
+## Objetivo (O QUE)
 
-## Plano de execução
+<Resultado esperado em 1-2 frases — o entregável concreto, observável.>
+
+### Entrega
+
+- <artefato 1 que esta task produz (componente, action, migration, story...)>
+- <artefato 2>
+
+## Arquivos (ONDE)
+
+> Caminhos exatos. Marque a operação. Sem isso o executor adivinha — proibido.
+
+| Operação | Path | Nota |
+|----------|------|------|
+| criar | `src/.../novo.tsx` | <o que é> |
+| editar | `src/.../existente.ts:NN` | <o que muda> |
+| deletar | `src/.../legado.tsx` | <só se `cleanup_target`> |
+
+## Plano de execução (COMO)
 
 - [ ] Passo 1
 - [ ] Passo 2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ganbatte-os",
-  "version": "0.2.37",
+  "version": "0.2.41",
   "description": "Framework operacional para design-to-code, squads de entrega e sprint sync com ClickUp.",
   "bin": {
     "gos": ".gos/scripts/cli/gos-cli.js"