ganbatte-os 0.2.33 → 0.2.35

package/.gos/templates/planTemplate.md

@@ -1,12 +1,14 @@
 ---
 id: PLAN-<NNN>-<slug>
 tela: <nome da tela>
+objetivo: <implantacao | correcao | refactor>
 figma_url: <url ou null>
 status: pendente
 parent_plan: <PLAN-NNN ou null>
 children_plans: []
 stack_ref: docs/stack.md@<sha-curto>
 arch_change: false
+work_branch: <dev | feat/storybook>
 created_at: <iso>
 validated_at: null
 ---
@@ -19,9 +21,41 @@ validated_at: null
 
 ## Componentes mapeados
 
-| Elemento | Componente do DS | Variant | Props |
-|----------|------------------|---------|-------|
-|          |                  |         |       |
+| Elemento | Componente do DS | Story (path) | Variant | Props | Comportamento |
+|----------|------------------|--------------|---------|-------|---------------|
+|          |                  |              |         |       |               |
+
+> Coluna `Comportamento` é **obrigatória** quando o elemento é interativo (row clicável, botão, input, drawer/modal/popup trigger). Refinamentos cosméticos da página (bg, border, padding) NÃO entram aqui — vão para `## Page-level overrides`.
+
+## Interações & Estados
+
+> Cobre o `INTERACOES` do prompt. Cada bullet = um caminho do usuário (trigger → ação → resultado/estado). `validate-plan` cruza essa lista contra tasks com `interaction_target:` no frontmatter.
+
+Fluxos por trigger:
+
+1. <ex: Lista → Row click → Drawer abre `mode=view` com record.id → fechar (X ou backdrop) → volta lista>
+2. <ex: Lista → "Novo X" → Drawer abre `mode=create` vazio → Salvar → POST /x → fecha + refetch + toast>
+3. <ex: Toolbar → mudar filtro Período → debounce 300ms → refetch query>
+
+Estados visuais por componente (skeleton / empty / error / loading):
+
+- <ex: Tabela: skeleton 5 rows enquanto fetch; empty state com ilustração + CTA "Criar primeiro X">
+- <ex: Drawer Salvar: estado loading com spinner + disabled durante POST>
+- <ex: Toolbar refresh: ícone gira durante refetch>
+
+## Page-level overrides
+
+> Refinamentos do Figma da página que divergem da story canônica. **Política**: Figma da página vence a story em conflitos cosméticos (bg, border, padding, radius). Cada override é uma decisão (a/b/c).
+
+| Componente | Override observado | Decisão | Ação |
+|------------|--------------------|---------|------|
+|            |                    |         |      |
+
+Decisões possíveis:
+
+- **(a) className na página** — override cosmético e isolado; mantém story padrão e aplica via classe na composição da página.
+- **(b) Nova variant na story** — override aparece em ≥3 telas do projeto; vira variant reusável (ex.: `flat`, `seamless`).
+- **(c) Exceção documentada** — override específico desta tela e não merece variant; documentado aqui sem propagar pra story.
 
 ## Componentes ausentes
 
@@ -68,9 +102,40 @@ validated_at: null
 - [ ] Sem console errors/warnings
 - [ ] TypeScript válido (`tsc --noEmit`)
 - [ ] Reutilização ≥ X% de componentes do DS
+- [ ] **Visual gate**: cada componente mapeado tem story em `dirs.stories/`
+- [ ] **Visual gate**: anatomia, tokens e densidade batem com a story canônica (≤ 1 desvio menor documentado em `T-NNN-NN.notes.md`)
+- [ ] **Visual gate**: árvore JSX da tela espelha hierarquia do Figma (mesmas seções, mesma ordem)
+- [ ] **Comportamentos**: cada linha de "Interações & Estados" tem implementação testável (handler conectado, refetch disparando, estado visual renderizado)
+- [ ] **Overrides**: cada linha de "Page-level overrides" foi resolvida pela decisão registrada (a/b/c)
+- [ ] **Variants**: story canônica reflete novas variants criadas (decisões `b`)
+- [ ] **States**: skeleton/empty/error/loading implementados conforme matriz acima
+- [ ] **Refetch**: dispara após mutações (POST/PATCH/DELETE)
+- [ ] **Seed**: popula TODOS os campos exibidos no Figma (sem `-` em colunas mapeadas)
 - [ ] <critério específico da tela 1>
 - [ ] <critério específico da tela 2>
 
+## Backend pendings
+
+> 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`).
+
+| gap-key | Gap | Endpoint/Coleção esperada | ClickUp ID | Status | Bloqueia tasks |
+|---------|-----|---------------------------|------------|--------|----------------|
+|         |     |                           |            |        |                |
+
+## Mock strategy
+
+> Opcional. Quando o frontend opta por mock enquanto o backend não atende, descreva aqui (ex.: fixture em `src/__mocks__/projetos.json`, MSW handler, etc.). Tasks que usam mock NÃO declaram `depends_on_backend:` — apenas referenciam esta seção.
+
+## Knowledge mapped
+
+> Inventário denso do que foi indexado no comprehension gate (regras-de-negocio + Postman).
+
+- **Regras de negócio**: `<lista de arquivos relevantes em docs/regras-de-negocio/>`
+- **Postman**: `<lista de coleções/endpoints relevantes em docs/postman/>`
+- **Stack ref**: `<sha de stack.md>`
+
 ## Riscos & Rollback
 
 - <risco>

package/.gos/templates/taskTemplate.md

@@ -9,6 +9,9 @@ priority: <P0|P1|P2>
 estimate: "<2h|4h|1d>"
 status: pendente
 valida_em: <referência ao critério no checklist do plano>
+depends_on_backend: []   # opcional — gap-keys da tabela ## Backend pendings do plano pai
+interaction_target: []   # opcional — bullets de "## Interações & Estados" do plano pai que esta task implementa/preserva (ex.: ["row-click-drawer-view", "submit-create"])
+override_target: []      # opcional — linhas de "## Page-level overrides" do plano pai que esta task resolve (ex.: ["StatCard:flat-variant"])
 assignees: []
 links: []
 ---
@@ -30,6 +33,9 @@ links: []
 ## Critérios de aceitação (DoD)
 
 - [ ] Implementação atende `valida_em` do plano
+- [ ] **Visual gate aprovado** (relatório em `T-NNN-NN.notes.md` com 5 seções: anatomia, tokens, variants, densidade, comportamentos)
+- [ ] **Comportamentos**: cada `interaction_target` declarado tem handler/estado implementado e observável no diff
+- [ ] **Overrides**: cada `override_target` declarado foi aplicado conforme decisão (a/b/c) registrada em `## Page-level overrides`
 - [ ] Tests/CI verdes
 - [ ] Sem regressões
 - [ ] <métrica específica>

package/CLAUDE.md

@@ -48,19 +48,26 @@ Todo texto gerado deve passar por correcao ortografica e remocao de padroes de I
 gos-master | architect | dev | devops | po | qa | sm | squad-creator | ux-design-expert
 
 ### Skills (invoke via /gos:skills:{slug})
-design-to-code | figma-implement-design | figma-make-analyzer | make-code-triage | make-version-diff | component-dedup | frontend-dev | interface-design | react-best-practices | react-doctor | sprint-planner | clickup | plan-to-tasks | agent-teams | git-ssh-setup | stack-profiler | plan-blueprint | progress-tracker
+design-to-code | figma-implement-design | figma-make-analyzer | make-code-triage | make-version-diff | component-dedup | frontend-dev | interface-design | react-best-practices | react-doctor | sprint-planner | clickup | plan-to-tasks | agent-teams | git-ssh-setup | stack-profiler | plan-blueprint | progress-tracker | execute-plan | validate-plan
+
+### IDEs suportadas (npm run sync:ides gera adapters)
+Claude Code | Cursor | Gemini CLI | Qwen Code | Antigravity | Opencode | Kilo Code | **Codex IDE Extension** (ambiente de execucao, comando primario `*execute-plan`)
 
 ## Plan Pipeline (stack-aware)
 
-Pipeline padronizado para criacao de planos por tela. Toda tela = 1 plano. Stack-of-record (`docs/stack.md`) e contrato — alteracoes de stack exigem ADR.
+Pipeline padronizado para criacao de planos por tela. Toda tela = 1 plano. Stack-of-record (`docs/stack.md`) e contrato — alteracoes de stack exigem ADR. Divisao de trabalho: **Opus 4.7 planeja, Codex IDE executa**.
+
+| Comando | Skill | IDE / Modelo | Funcao |
+|---------|-------|--------------|--------|
+| `*stack [refresh|show|drift]` | `stack-profiler` | qualquer | Mantem `docs/stack.md` (canonico do projeto) |
+| `*plan <tela>` | `plan-blueprint` | Opus 4.7 (planejador) | Cria plano + tasks + context + atualiza `progress.txt`. Captura comportamentos (`## Interacoes & Estados`) e page-level overrides (`## Page-level overrides`). INTERACOES obrigatorio quando tela tem table-clicavel/drawer/modal/popup. |
+| `*execute-plan <PLAN-NNN>` | `execute-plan` | **Codex IDE Extension** (executor) | Executa task-a-task com visual gate (5 dim: anatomia, tokens, variants, densidade, comportamentos) vs Storybook canonico. Pre-flight smoke compara screenshot da pagina vs Figma frame antes da T-01. Non-blocking em backend gaps. |
+| `*validate-plan <PLAN-NNN>` | `validate-plan` | Opus 4.7 (revisor) | Valida pos-execute; auto-marca concluido tasks que passam em checklist + visual gate curto + diff |
+| `*progress [show|set|status]` | `progress-tracker` | qualquer | Memoria L1 + state machine de status |
 
-| Comando | Skill | Funcao |
-|---------|-------|--------|
-| `*stack [refresh|show|drift]` | `stack-profiler` | Mantem `docs/stack.md` (canonico do projeto) |
-| `*plan <tela>` | `plan-blueprint` | Cria plano + tasks + context + atualiza `progress.txt` |
-| `*progress [show|set|status]` | `progress-tracker` | Memoria L1 + state machine de status |
+State machine: `pendente -> em-andamento -> validacao -> concluido`. Estado lateral `bloqueada-backend` (introduzido pelo `*execute-plan` quando task tem `depends_on_backend:` em aberto no ClickUp; libera quando ClickUp fecha). `concluido` marcado automaticamente pelo `*validate-plan` quando passa em checklist + visual gate curto + diff + cobertura de `interaction_target`/`override_target`.
 
-State machine: `pendente -> em-andamento -> validacao -> concluido` (concluido somente apos validacao humana).
+**Politica Figma vs Storybook**: story define API/anatomia do componente; em conflito visual cosmetico (bg, border, padding, radius), Figma da pagina vence — divergencia e registrada em `## Page-level overrides` do plano com decisao a/b/c (a=className, b=variant nova, c=excecao documentada). Sem essa disciplina, refinamentos da pagina viram retrabalho no fim (caso PLAN-005: 54 deltas em 26 rodadas).
 
 Paths do projeto-cliente sao resolvidos via `.gos-local/plan-paths.json` — nada hardcoded. Nesse arquivo declara-se onde estao `docs/plans/`, `docs/postman/`, `docs/regras-de-negocio/`, design system, etc. Cada projeto/dev pode organizar diferente.
 

package/package.json

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