ganbatte-os 0.2.33 → 0.2.35

package/.gos/skills/execute-plan/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: execute-plan
+description: Executa um plano (PLAN-NNN-<slug>) task-a-task aplicando state machine + visual gate contra Storybook canonico antes de marcar validacao. Non-blocking em backend gaps (abre tasks ClickUp + segue). Comando primario do ambiente Codex IDE.
+argument-hint: "<PLAN-NNN-slug> [--task T-NNN-NN] [--skip-visual-gate] [--skip-clickup]"
+allowedTools: [Read, Glob, Grep, Bash, Write, Edit, Agent, AskUserQuestion]
+sourceDocs:
+  - templates/taskTemplate.md
+  - playbooks/plan-creation-playbook.md
+  - skills/figma-implement-design/SKILL.md
+  - skills/plan-blueprint/SKILL.md
+use-when:
+  - executar plano ja criado por *plan
+  - rodar tasks de um PLAN-NNN com state machine e visual gate
+  - ambiente Codex IDE Extension (comando primario)
+do-not-use-for:
+  - criar plano novo (use plan-blueprint)
+  - decompor plano em tasks (use plan-to-tasks)
+  - gerenciar progress.txt isoladamente (use progress-tracker)
+metadata:
+  category: execution
+---
+
+Voce esta executando como **Executor de Planos** via skill `execute-plan`. No ambiente Codex IDE Extension este e o comando primario do ciclo `Opus(plan) -> Codex(execute)`.
+
+## Input
+
+$ARGUMENTS
+
+Formato esperado:
+- `<PLAN-NNN-slug>` — id do plano (ex.: `PLAN-001-pagina-projetos-inicial`)
+- `--task T-NNN-NN` — opcional, executa apenas a task especifica
+- `--skip-visual-gate` — opcional, pula visual gate (raro, registra warning)
+
+## Pre-requisitos (gate)
+
+1. Resolver paths via `.gos-local/plan-paths.json`. Se ausente, abortar e instruir o usuario a rodar `*plan` primeiro.
+2. Localizar `<dirs.planos>/<PLAN-NNN-slug>/plan.md`. Se ausente, abortar.
+3. Ler `plan.md` por completo: frontmatter + Componentes mapeados + Componentes ausentes + Aderencia a stack + Plano de execucao + Checklist de aceite + **Backend pendings**.
+4. Validar `stack_ref` do frontmatter contra `<dirs.stack>` (`docs/stack.md`):
+   - Calcular sha-curto atual e comparar.
+   - Drift detectado: ABORTAR e instruir `*stack drift` + replanejar com `*stack refresh`.
+5. Ler `<dirs.progress>` (progress.txt). Se aponta para outro plano ativo, perguntar se troca o foco antes de prosseguir.
+6. **Backend pendings (non-blocking)**: ler tabela `## Backend pendings` do `plan.md`. Para cada linha:
+   - Sem `ClickUp ID` -> criar task via `mcp__clickup__clickup_create_task` (assignee `112010775` salvo override `ASSIGNEE` no plano, list de `clickup.backend_list_id` em `plan-paths.json`, titulo `[Backend] PLAN-NNN: <gap>`). Gravar ID retornado de volta na coluna `ClickUp ID` do `plan.md`.
+   - Com `ClickUp ID` -> consultar `mcp__clickup__clickup_get_task <ID>`. Atualizar coluna `Status`. Se ainda aberta, registrar em `progress.txt` como `blockers=<T-IDs>:<ClickUp-ID>:<gap-curto>` (uma linha por bloqueio ativo).
+   - `--skip-clickup` desliga MCP; nesse caso so registra warning visivel mantendo o que ja esta no plano.
+   - **Importante**: backend gap aberto NAO aborta o execute-plan. Tasks frontend que dependem do gap serao classificadas como `bloqueada-backend` no loop abaixo; tasks sem dependencia seguem normal.
+
+## Pre-flight visual
+
+(Pulado quando `--skip-visual-gate` presente — registrar warning em `tasks/T-NNN-NN.notes.md` da primeira task.)
+
+1. Resolver `<dirs.storybook>` via `plan-paths.json`. Path absoluto fora do repo do projeto e valido (ex.: `E:\Github\Ganbatte\tmp\fractus-storybook`).
+2. Indexar todos `.stories.tsx` disponiveis em `<dirs.stories>` ou `<dirs.components>`.
+3. Para cada linha da tabela "Componentes mapeados" do plano:
+   - Confirmar que a coluna `Story (path)` aponta para arquivo existente.
+   - Se ausente: gerar task de criacao do componente ANTES das tasks de implementacao. Renumerar `seq` das tasks restantes.
+4. Output do pre-flight: bloco em `progress.txt` campo `notes=` com numero de stories indexadas e tasks de criacao geradas.
+
+## Pre-flight visual smoke (NOVO)
+
+Antes da T-01 (depois do pre-flight de stories acima), gera comparacao visual entre pagina renderizada e frame Figma para capturar gaps grandes ANTES da execucao — evita o padrao PLAN-005 onde feedback iterativo gerou 26 rodadas no fim.
+
+Ativacao:
+- Storybook disponivel: usa `.stories.tsx` da pagina-completa quando existe (ex.: `ProjetosPage.stories.tsx`) e renderiza via `npm run storybook -- --static-build` ou screenshot ja gerado em CI.
+- Playwright MCP disponivel (`mcp__plugin_playwright_playwright__*`): navega para localhost (rota da pagina + seed declarado em `## Mock strategy` ou seed nativo do projeto) e captura screenshot.
+- Nenhum disponivel: pula com warning em `progress.txt` (`smoke=skipped: no storybook story for full page nor playwright MCP`). NAO bloqueia.
+
+Comparacao:
+1. Carrega frame Figma principal (`figma_url` do plano) via Figma MCP — extrai layout/secoes esperadas.
+2. Confronta screenshot vs frame em 3 dimensoes basicas (sem refazer 4-dim por componente — isso fica no gate por task):
+   - **Secoes presentes**: KPI row, toolbar, table, drawer trigger, etc. — cada secao esperada esta no screenshot?
+   - **Layout grosseiro**: ordem vertical das secoes; colunas da table batem com Figma?
+   - **Cores/tokens primarios**: bg da pagina, accent color, contrast — sem inversao obvia.
+3. Output: `<dirs.planos>/<PLAN-NNN-slug>/preflight-smoke.md` com lista de gaps detectados (secao faltando, layout invertido, cor errada).
+4. Se gaps detectados: gerar tasks `T-000-XX` (prefixo `000` = pre-flight) com `priority: P0` e prepend no inicio da fila. Renumerar `seq` das tasks subsequentes.
+
+Pre-flight smoke nao substitui o visual gate por task — ele captura gaps grandes (componente faltando, KPI row ausente) que viraram tasks novas em PLAN-004/PLAN-005.
+
+## Loop por task
+
+Iterar tasks em ordem de `seq`. Antes de executar cada task, **classificar**:
+
+- Ler frontmatter `depends_on_backend:` da task (campo opcional, default `[]`). Cada item referencia uma `gap-key` da tabela `## Backend pendings` do plano (ex.: `migration-20260501150000`, `endpoint-projetos-fields`).
+- Se a task referencia gap em aberto (status no ClickUp != `concluido`/`closed`):
+  - `*progress status T-NNN-NN bloqueada-backend` (transicao livre desde `pendente` ou `em-andamento`).
+  - Anotar em `tasks/T-NNN-NN.notes.md` linha `## Bloqueada backend <iso>` com ClickUp IDs.
+  - **PULAR** task — NAO falha o loop, segue pra proxima.
+- Se a task tem `depends_on_backend: []` ou todas as dependencias estao `concluido` no ClickUp -> seguir fluxo normal abaixo.
+
+Para cada task **executavel**:
+
+0. **Pre-flight da task — gate de formato**: ler `tasks/T-NNN-NN*.md`. Confirmar que tem frontmatter YAML (`head -1 == "---"`) e contém `^status:` no frontmatter. Se ausente: ABORTAR a task com erro `task-malformada: T-NNN-NN sem frontmatter status — rodar plan-to-tasks regenerador OU migrate-task-status.js`. NUNCA tentar executar codigo sem frontmatter valido — sintoma do bug onde tasks ficam travadas em `pendente`.
+1. **Mover para em-andamento**: invocar `*progress status T-NNN-NN em-andamento` (skill `progress-tracker`). **Pos-condicao obrigatoria**: ler T-NNN-NN.md de novo e confirmar `^status: em-andamento$` no frontmatter. Se nao mudou: ABORTAR e instruir humano. NAO seguir para implementacao com status pendente — esse e o bug central reportado.
+2. **Despachar agent**: ler `labels: [agent:<slug>]` da task. Default: `dev`. Invocar via Agent tool com prompt completo (objetivo, plano de execucao, DoD, paths relevantes).
+3. **Implementacao**: agent edita arquivos seguindo o plano de execucao da task. Stack como contrato — nada fora de `docs/stack.md` salvo se `arch_change=true` no frontmatter do plano pai.
+4. **Visual gate** (antes de propor `validacao`):
+
+   Para cada componente alterado/criado pela task:
+
+   a) Localizar `<Componente>.stories.tsx` em `<dirs.storybook>`.
+   b) Comparar implementacao vs story canonica em 5 dimensoes textuais:
+      - **Anatomia**: ordem de slots/elementos (header -> corpo -> footer; icones esquerda/direita; campos do form na ordem do design).
+      - **Tokens**: classes Tailwind/variaveis CSS batem com DS (cor, raio, espacamento, tipografia). Quando o componente aparece em `## Page-level overrides` do plano: a divergencia cosmetica registrada NAO falha o gate — o gate confirma que o override foi APLICADO conforme decisao (a/b/c).
+      - **Variants**: props expostos cobrem variants da story. Decisao (b) em `## Page-level overrides`: confirmar que a nova variant existe na story canonica.
+      - **Densidade**: padding/gap dentro de +-1 step da escala do DS (ou conforme override registrado).
+      - **Comportamentos** (NOVO, heuristico via JSX + grep, sem E2E):
+        - Para cada `interaction_target:` declarado no frontmatter da task: existe handler implementado no diff? (ex.: `row.onClick` chamando `openDrawer`; `button.onClick` chamando mutation; `form.onSubmit` chamando server action).
+        - Estados visuais (skeleton/empty/error/loading) declarados em `## Interações & Estados` renderizam? grep por `isLoading|isPending|isError|empty|skeleton` nos arquivos tocados.
+        - Refetch apos mutation: `invalidateQueries` / `router.refresh` / `setState` observavel no diff?
+        - Para cada `override_target:` declarado: classes/props da decisao (a/b/c) presentes no diff? grep das classes declaradas em `## Page-level overrides`.
+   c) Para a tela como um todo: invocar Figma MCP no `figma_url` do plano e cruzar com o JSX renderizado em arvore (mesmo numero de secoes, mesma hierarquia, mesmas labels).
+   d) Output: relatorio curto em `tasks/T-NNN-NN.notes.md` (5 secoes: anatomia, tokens, variants, densidade, comportamentos + secao "Arvore vs Figma").
+   e) Divergencia >= 1 item critico (anatomia, tokens nao-overrideados, ou comportamento mapeado sem implementacao) -> falha o gate.
+
+5. **Resultado do gate**:
+   - Sucesso -> invocar `*progress status T-NNN-NN validacao`. **Pos-condicao obrigatoria**: ler T-NNN-NN.md, confirmar `^status: validacao$` no frontmatter. Se nao mudou: ABORTAR a task com erro `progress-tracker-falhou: T-NNN-NN`. Preparar arquivos staged (sem commit) somente apos confirmacao.
+   - Falha -> manter em `em-andamento`, gravar diff em `T-NNN-NN.notes.md`, retornar pra etapa 3.
+
+**Invariante por task**: ao terminar a iteracao, T-NNN-NN.md DEVE ter status diferente de `pendente`. Se ainda for `pendente` apos a iteracao, registrar como bug do executor em `progress.txt` (`notes=executor-skipped-progress: T-NNN-NN`) e abortar o loop — sintoma do bug original.
+
+## Fechamento
+
+Quando o loop terminar (todas as tasks executaveis em `validacao` ou puladas em `bloqueada-backend`):
+
+1. Listar arquivos modificados via `git diff --name-only`.
+2. Preparar commit (NAO push). Mensagem segue Conventional Commits + referencia ao `PLAN-NNN-slug`. Se houve tasks bloqueadas, citar na mensagem (ex.: `feat(checkout): PLAN-042 T-01..T-05 (T-06,T-07 bloqueadas backend CU-XXX)`).
+3. Resumo final ao usuario em 4 blocos:
+   ```
+   [execute-plan] PLAN-NNN-<slug>
+
+   tasks validacao:    <N>  (T-..., T-...)
+   bloqueada-backend:  <K>  (T-...:CU-..., ...)
+   backend pendings:   <X>  abertas no ClickUp / <Y> concluidas
+   visual gate:        passou / falhou em (T-...)
+
+   proximo passo: *validate-plan PLAN-NNN-<slug>
+   ```
+4. Indicar que o turn seguinte e `*validate-plan PLAN-NNN-<slug>` (skill `validate-plan`, ambiente Opus 4.7). NAO marcar `concluido` automaticamente — `validate-plan` cuida disso.
+
+## Ambiente Codex IDE — observacoes
+
+- O usuario invoca `*execute-plan` direto no Codex. A skill carrega via wrapper em `.codex/skills/gos-execute-plan/SKILL.md`.
+- Toda chamada a outros agents/skills do G-OS dentro do execute-plan deve usar o adapter Codex correspondente (`.codex/agents/`, `.codex/commands/`).
+- Se a chamada cair pra outro adapter (Claude/Qwen/etc) a sessao quebra — abortar com mensagem clara.
+
+## Regras criticas
+
+- **Visual gate nao e opcional** salvo `--skip-visual-gate` explicito. Skill nao silencia o gate.
+- **Sem push automatico**: commit fica preparado. Push e responsabilidade do humano.
+- **State machine inviolavel**: transicao `concluido` ocorre via `*validate-plan` (auto-marca quando passa). Rollback humano: `*progress status T-NNN-NN pendente --rollback`.
+- **Non-blocking em backend gaps**: gap aberto no ClickUp NAO aborta. Tasks dependentes viram `bloqueada-backend`, demais seguem.
+- **Storybook como contrato base; Figma da pagina vence em conflito cosmetico**: componente sem `.stories.tsx` em `<dirs.storybook>` bloqueia a task ate ser criado. Divergencia cosmetica entre story e Figma da pagina que ESTA registrada em `## Page-level overrides` do plano: gate confirma aplicacao do override (decisao a/b/c). Divergencia NAO registrada no plano: gate falha — voltar pra `*plan` (ou registrar override no plan.md antes de prosseguir).
+- **Comportamento mapeado e vinculante**: `interaction_target:` declarado na task DEVE ter handler/estado implementado e observavel no diff. Caso contrario, gate falha mesmo se anatomia + tokens passarem.
+
+## Model guidance
+
+| Escopo | Modelo |
+|--------|--------|
+| Task simples (1 componente, sem novo padrao) | `sonnet` |
+| Task que toca multiplos componentes ou logica de fetching | `opus` |
+| Visual gate / comparacao com Figma | inherit (modelo do agent) |
+
+## Instructions
+
+1. NUNCA pular o pre-flight visual sem flag explicita.
+2. Resolver TODOS os paths via `plan-paths.json`.
+3. Visual gate produz relatorio em `T-NNN-NN.notes.md` mesmo em caso de sucesso.
+4. Status final esperado: todas as tasks em `validacao`, commit preparado, humano notificado.

package/.gos/skills/plan-blueprint/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: plan-blueprint
 description: Cria um plano padronizado para uma tela (1 plano = 1 tela) seguindo a stack-of-record do projeto. Produz {plano, tasks, contexto, entrada-progress.txt} em três fases (Mapeamento → Aderência à stack → Execução). Pré-requisito duro: docs/stack.md existir. Subdivide automaticamente telas com seções autônomas múltiplas.
-argument-hint: "<tela|figma-url|descrição> [--from-figma-mcp] [--allow-arch-change]"
+argument-hint: "<tela> OBJETIVO=<implantacao|correcao|refactor> FIGMA=<url> [FIGMA+=...] [--from-figma-mcp] [--allow-arch-change] [--skip-clickup]"
 allowedTools: [Read, Glob, Grep, Bash, Write, Edit, Agent, AskUserQuestion]
 sourceDocs:
   - templates/planTemplate.md
@@ -21,18 +21,52 @@ metadata:
 
 Você está executando como **Tech Lead Frontend / Arquiteto Sênior** via skill `plan-blueprint`.
 
+## Contrato inviolável
+
+`*plan` é uma operação **atômica** que entrega `{plan.md + context.md + TODAS as T-NN*.md no tasks/ + progress.txt atualizado}`. NUNCA termine sem todos os 4 artefatos. A sequência obrigatória ao final é:
+
+1. Escrever `plan.md` + `context.md`.
+2. **Invocar `plan-to-tasks`** apontando para o `plan.md` recém-criado — gera os `T-NN*.md` em `tasks/`.
+3. Atualizar `progress.txt` (skill `progress-tracker set`).
+4. **Rodar `node <repo>/.gos/scripts/integrations/check-plan.js <plan-dir>`** — gate determinístico.
+5. Exit 0 → devolver "plano criado" com resumo. Exit != 0 → regerar tasks 1x e re-rodar; se persistir, ABORTAR e devolver a saída do check-plan ao usuário.
+
+Plano sem tasks (tasks/ vazio ou ausente) é falha — não é "plano parcial". Skill que devolve "plano criado" sem ter rodado o check-plan está em estado inválido.
+
 ## Input
 
 $ARGUMENTS
 
-Auto-detecção de input:
-- URL `https://www.figma.com/...` → ativa modo Figma MCP
-- caminho de arquivo `.md`/`.png`/`.jpg` → modo descrição com referência visual
-- texto livre → modo descrição
+Campos obrigatórios no prompt:
+- `OBJETIVO` — `implantacao` | `correcao` | `refactor`
+- `FIGMA` — URL do frame principal (auto-ativa Figma MCP)
+- `INTERACOES` — lista estruturada de interações da tela (`<Elemento> — <trigger> → <ação> → <resultado>`). **Obrigatório quando a tela tem table com row clicável OU drawer/modal/popup OU botão que dispara ação assíncrona**. `gos-master` recusa o `*plan` se vazio nessas condições.
+
+Opcionais:
+- `FIGMA+` — lista de URLs de componentes
+- `NOTAS` — prosa livre (invioláveis, edge cases, contexto adicional)
+- `ASSIGNEE` — override do user_id ClickUp para tasks de backend (default: 112010775)
+
+Auto-resolvido pelo `gos-master` (comprehension gate, NÃO pedir ao usuário):
+- `PROJETO` — `cwd`; ambíguo → `~/.claude/.gos-state/last-project.json`
+- `WORK_BRANCH` — tela em Storybook → `feat/storybook`; senão → `dev`
+- `STORYBOOK_DIR/BRANCH` — `plan-paths.json`
+- `BUSINESS_RULES` — `<PROJETO>/docs/regras-de-negocio/` (indexar e registrar em progress.txt)
+- `POSTMAN` — `<PROJETO>/docs/postman/` (idem)
+- `BACKEND/RLS/SEED/SMOKE_E2E` — derivado de `stack.md` + regras + Postman
+
+OBJETIVO muda postura:
+
+| Valor | Comportamento |
+|-------|---------------|
+| `implantacao` | Cria do zero — Fase 1 → 2 → 3 padrão |
+| `correcao` | Modo cirúrgico — diff vs Storybook canônico, 1 task por componente, sem reescrever |
+| `refactor` | Implica `--allow-arch-change` + ADR obrigatória |
 
 Flags:
-- `--from-figma-mcp` — força leitura via Figma MCP
-- `--allow-arch-change` — libera Fase 2 propositiva (gera ADR)
+- `--from-figma-mcp` — força leitura via Figma MCP (default quando `FIGMA=` é Figma URL)
+- `--allow-arch-change` — libera Fase 2 propositiva (gera ADR); implícito em `OBJETIVO=refactor`
+- `--skip-clickup` — não cria tasks de backend automaticamente
 
 ## Pré-requisitos (gate)
 
@@ -41,6 +75,9 @@ Flags:
    - Se ausente: ABORTAR. Despachar `stack-profiler refresh` e instruir o usuário a re-executar.
    - Se presente: ler integralmente. Verificar drift via `*stack drift` antes de prosseguir.
 3. Ler `progress.txt` se existir (memória L1).
+4. **Verificar `dirs.storybook`** (caminho do `plan-paths.json`):
+   - Se ausente OU diretório não existe: ABORTAR. Pedir caminho ao usuário (path absoluto fora do repo é válido, ex.: `E:\Github\Ganbatte\tmp\fractus-storybook`) e gravar em `plan-paths.json`.
+   - Se presente: indexar `.stories.tsx` disponíveis (lista usada na Fase 1.3).
 
 ## Fase 1 — Mapeamento Visual & Componentização
 
@@ -60,11 +97,37 @@ Caso contrário: trabalhar pela descrição/screenshot fornecido.
 
 Produzir tabela:
 
-| Elemento (Figma/descrição) | Componente do DS | Variant | Props relevantes |
-|----------------------------|------------------|---------|-------------------|
+| Elemento (Figma/descrição) | Componente do DS | Story (path) | Variant | Props relevantes | Comportamento |
+|----------------------------|------------------|--------------|---------|-------------------|---------------|
+
+A coluna `Story (path)` aponta para `.stories.tsx` indexado no gate. Componente sem story correspondente NÃO entra na tabela — vai pra "Componentes ausentes" e gera task de criação.
+
+Coluna `Comportamento` é obrigatória quando o elemento é interativo. Refinamentos cosméticos (bg, border, padding) NÃO entram aqui — vão para `## Page-level overrides` (Fase 1.4 abaixo).
 
 Listar **componentes ausentes** separadamente — sinalizar como bloqueio ou candidato a criação (vai virar task própria).
 
+### 1.4 Comportamentos & Overrides
+
+Sub-fase nova que materializa intenção de uso e divergência Figma↔Storybook:
+
+1. **Interações & Estados** (`## Interações & Estados` no plano):
+   - Lê `INTERACOES` do input. Se ausente E a tela tem table/drawer/modal/popup detectado em Figma MCP (layer names contendo `Drawer|Modal|Dialog|Popup|Sheet`) ou em `dirs.app` (página equivalente já existente): **bloqueia** a geração e devolve `AskUserQuestion` estruturado pedindo as interações com 3 exemplos pré-preenchidos (clickable row, submit, filtro).
+   - Reconcilia `INTERACOES` com Figma MCP prototype connections quando disponíveis (`figma.connections` revela frame→frame transitions). Conflito → prefere `INTERACOES` do usuário (intenção declarada).
+   - Cada bullet vira identificável (slug curto: `row-click-drawer-view`, `submit-create`, `filter-periodo`) — esses slugs são referenciados por `interaction_target:` nas tasks.
+   - Mapa de estados visuais (skeleton/empty/error/loading) por componente é obrigatório quando a tabela "Componentes mapeados" inclui Tabela ou Form.
+
+2. **Page-level overrides** (`## Page-level overrides` no plano):
+   - Para cada componente da tabela "Componentes mapeados": confronta CSS aplicado no Figma da página (padding, border, bg, radius, shadow) contra props/classes da story canônica em `.stories.tsx`.
+   - Diff cosmético vira linha em `## Page-level overrides` com decisão sugerida pela heurística:
+     - Override aparece em ≥3 telas do projeto (grep em `dirs.app`): **(b) nova variant na story**.
+     - Override aparece só nesta tela: **(a) className na página**.
+     - Override é workaround conhecido / hack temporário: **(c) exceção documentada**.
+   - Slugs curtos (`StatCard:flat-variant`, `Drawer:no-outer-border`) são referenciados por `override_target:` nas tasks.
+
+Política Figma vs Storybook (ver Fase 2):
+
+> Story define API/anatomia do componente; refinamentos cosméticos da página são aceitos via override registrado em `## Page-level overrides`. **Em conflito visual, Figma da página vence**.
+
 ## Fase 2 — Aderência à Stack
 
 **Modo padrão (sem `--allow-arch-change`)**: SOMENTE referenciar a stack já registrada em `stack.md`. Para cada dado/ação da tela, listar:
@@ -77,6 +140,22 @@ Saída desta fase é uma seção **"Aderência à Stack"** no plano — não red
 
 **Modo `--allow-arch-change`**: pode propor alteração. Gerar ADR em `dirs.adr` (template `templates/adr-tmpl.yaml`) ANTES de prosseguir. Plano referencia o ADR e marca `arch_change: true` no frontmatter.
 
+### 2.5 Backend gaps → ClickUp automático
+
+Postman é o **contrato backend**. Para cada dado/ação da tela:
+
+1. Confrontar com `<PROJETO>/docs/postman/` (já indexado no comprehension gate).
+2. Se o endpoint não existir, ou existir com shape divergente, ou faltar RLS/migration para suportar a tela → registrar como **backend pending**.
+3. Para cada pending, criar task ClickUp via `mcp__clickup__clickup_create_task`:
+   - **Assignee**: `ASSIGNEE` do prompt OU default `112010775` (Douglas Oliveira).
+   - **List**: `clickup.backend_list_id` de `plan-paths.json`. Ausente → registrar pending no plano com `clickup: pending` e seguir.
+   - **Título**: `[Backend] PLAN-NNN: <gap em uma linha>`
+   - **Descrição**: o que a tela precisa, qual coleção/endpoint do Postman cobre (ou não), referência ao plano (`docs/plans/PLAN-NNN/plan.md`), shape esperado.
+4. Registrar IDs criados em:
+   - `plan.md` → seção `## Backend pendings` (lista com `clickup_id`, status, link).
+   - `progress.txt` → bloco `## Backend pendings — PLAN-NNN`.
+5. Flag `--skip-clickup` desliga a criação (pending fica registrado apenas no plano).
+
 ## Fase 3 — Plano de Execução
 
 Para cada elemento mapeado:
@@ -86,6 +165,12 @@ Para cada elemento mapeado:
 3. Montagem da view (composição dos componentes do DS)
 4. Estado e interatividade (client components estritamente onde necessário)
 
+Regras de geração de tasks (cobertura de comportamento + overrides):
+
+- Toda interação em `## Interações & Estados` deve gerar **ao menos 1 task** com `interaction_target:` apontando pra ela. Se uma task cobre múltiplas interações, listar todos os slugs.
+- Toda linha de `## Page-level overrides` com decisão **(b)** gera task de variant na story (`area: ui-ux`, `agent:ux-design-expert`); decisões **(a)** e **(c)** geram tasks na página (`area: frontend`, `agent:dev`). Em ambos os casos, frontmatter da task declara `override_target:` apontando pro slug.
+- Tasks de seed data (quando aplicável — Tabela ou Form com fields no Figma) declaram fields obrigatórios e referenciam o checklist "Seed popula TODOS os campos exibidos".
+
 ## Subdivisão automática
 
 Se a análise identificar mais de 3 seções autônomas (modais, drawers, sub-rotas com fetching próprio), gerar **planos filhos** numerados:
@@ -97,13 +182,34 @@ Frontmatter linka via `parent_plan` / `children_plans`.
 
 ## Saída
 
-Para cada plano (incluindo filhos):
+Para cada plano (incluindo filhos), os 4 passos abaixo são **obrigatórios e atômicos** — `*plan` NÃO termina sem todos. Falhar qualquer um aborta com erro explícito (não retornar plano-sem-tasks ao usuário; foi exatamente isso que motivou o bug do PLAN-006).
 
 1. `<dirs.planos>/PLAN-NNN-<slug>/plan.md` — gerado a partir de `templates/planTemplate.md`. Frontmatter inclui `stack_ref: <dirs.stack>@<sha-curto>` para travar a versão da stack.
 2. `<dirs.planos>/PLAN-NNN-<slug>/context.md` — gerado a partir de `templates/contextTemplate.md`. Denso, indexado.
-3. Disparar `plan-to-tasks` automaticamente apontando para o `plan.md` recém-criado → produz tasks em `<dirs.tasks>` (resolvido com `{plan}` substituído).
+3. **Disparar `plan-to-tasks`** apontando para o `plan.md` recém-criado → produz tasks em `<dirs.tasks>` (resolvido com `{plan}` substituído). Esta chamada é **vinculante** — `*plan` é uma operação `{plano + tasks + context + progress}`, nunca só plano. Se `plan-to-tasks` falhar (gate de Phase 3.5), abortar `*plan` inteiro (não deixar plano órfão).
 4. Disparar `progress-tracker set-current` apontando o plano novo → atualiza `progress.txt`.
 
+**Pós-condições obrigatórias** (verificar antes de devolver controle ao usuário):
+
+- `<dirs.planos>/PLAN-NNN-<slug>/tasks/` existe e contém ≥1 `T-NN*.md`.
+- Para CADA `T-NN*.md`: `head -1` = `---` E grep `^status: pendente$` retorna match. Use o gate da Phase 3.5 do `plan-to-tasks`. Falha → regerar tasks; se persistir, abortar com erro explícito ao usuário citando os arquivos malformados.
+- `progress.txt` aponta para o plano novo.
+
+### Gate determinístico — ÚLTIMA ação obrigatória do `*plan`
+
+Após escrever todos os arquivos e atualizar `progress.txt`, **executar via Bash**:
+
+```bash
+node <repo-do-framework>/.gos/scripts/integrations/check-plan.js <dirs.planos>/PLAN-NNN-<slug>
+```
+
+(No projeto-cliente o caminho do script é `.gos/scripts/integrations/check-plan.js`. Em workspaces que rodam o G-OS canônico, é `.G-OS/.gos/scripts/integrations/check-plan.js`.)
+
+- **Exit code 0** → plano válido, usável por `*execute-plan` / `*validate-plan`. SÓ ENTÃO devolver "plano criado" ao usuário com o resumo final.
+- **Exit code != 0** → NÃO devolver "plano criado". A saída do script aponta exatamente o que está errado (task sem frontmatter, status divergente, secao `## Status` no body, etc.). Tentar regerar via `plan-to-tasks` UMA vez; se persistir, abortar com a saída do `check-plan` literal e instruir o usuário a rodar `migrate-task-status.js`.
+
+Esse gate é **determinístico** — não depende do LLM verificar individualmente cada task. É a barreira que evita o bug PLAN-006 voltar.
+
 Resumo final:
 
 ```
@@ -127,6 +233,8 @@ Próximos passos:
 - **Backend read-only respeitado**: se `stack.md` declara backend read-only, plano NUNCA propõe schema novo.
 - **Next.js App Router**: decisão server vs client é explícita por elemento.
 - **Sem prosa decorativa**: plano deve ser executável, denso, com critérios mensuráveis.
+- **Storybook como contrato base; Figma da página como contrato final**: cada componente do DS na tabela DEVE apontar `.stories.tsx` existente em `dirs.storybook`. Sem story → componente vai pra "Componentes ausentes" e gera task de criação. **Em conflito visual entre story e Figma da página, Figma vence** — divergência cosmética é registrada em `## Page-level overrides` com decisão a/b/c (não vira retrabalho no fim).
+- **Comportamento mapeado é obrigatório**: tela com table-clicável/drawer/modal/popup sem `INTERACOES` no input bloqueia plan generation (`AskUserQuestion`). Sem essa disciplina, o caso PLAN-005 (54 deltas em 26 rodadas de feedback) repete.
 
 ## Model guidance
 
@@ -139,6 +247,7 @@ Próximos passos:
 ## Instructions
 
 1. NUNCA prosseguir sem `stack.md` válido.
-2. Resolver TODOS os paths via `plan-paths.json`.
+2. Resolver TODOS os paths via `plan-paths.json`. PROJETO/WORK_BRANCH são auto-resolvidos pelo `gos-master` — não perguntar ao usuário.
 3. Status inicial do plano e tasks: `pendente`.
 4. Não pushar nada — apenas escrever arquivos locais.
+5. Backend pendings só criam tasks ClickUp se o `mcp__clickup__*` estiver disponível na sessão E `--skip-clickup` não for passado. Caso contrário, registrar apenas no plano.

package/.gos/skills/plan-to-tasks/SKILL.md

@@ -49,40 +49,24 @@ For each task, create a file following o caminho resolvido em `plan-paths.json`:
 
 Naming: usar `naming.task_prefix` e `naming.seq_padding` do `plan-paths.json` (defaults: `T`, padding 3 → `T-042-001`).
 
-Use this template (from `templates/taskTemplate.md`):
+**Template — CONTRATO DURO**: a estrutura canônica vive em `templates/taskTemplate.md`. Esta skill **DEVE ler esse arquivo na Phase 1** e usar **exatamente** os campos do frontmatter de lá — sem omitir, renomear ou reordenar. NÃO reproduza template inline aqui (já causou bug onde tasks geradas não tinham `status:` no frontmatter — rastreável a planos com tasks travadas em `pendente` mesmo após execução).
 
-```markdown
----
-id: TASK-<YYYYMM>-<seq>
-title: <imperative action verb + what>
-area: <security|backend|ui-ux|routers|migrations|tests|general>
-labels: [agent:<slug>, type:<refactor|bug|feature|chore>]
-priority: <P0|P1|P2>
-estimate: "<2h|4h|1d>"
-assignees: []
-due: null
-links: []
----
-
-## Contexto
-<why this task exists — link to the source plan/ADR/PRD>
+Campos obrigatórios do frontmatter (do `taskTemplate.md`, presentes em CADA T-NN.md gerado):
+- `id`, `plan_id`, `seq`, `title`, `area`, `labels`, `priority`, `estimate`
+- **`status: pendente`** — invariante. Sem isso o `progress-tracker` não consegue transicionar e o `*execute-plan`/`*validate-plan` quebram.
+- `valida_em`, `depends_on_backend: []`, `interaction_target: []`, `override_target: []`, `assignees: []`, `links: []`
 
-## Objetivo
-<expected result in 1-2 sentences>
+Body: copiar as seções do `taskTemplate.md` (`## Contexto`, `## Objetivo`, `## Plano de execução`, `## Critérios de aceitação (DoD)`, `## Riscos & Rollback`) — **NÃO** adicionar seção `## Status` no body. Status vive APENAS no frontmatter.
 
-## Plano de execução
-- [ ] Step 1
-- [ ] Step 2
-- [ ] Step 3
+### Phase 3.5 — Verificação pós-geração (gate)
 
-## Critérios de aceitação (DoD)
-- [ ] Tests/CI green
-- [ ] No regressions
-- [ ] <measurable metric: e.g., coverage ≥70% | endpoint returns <200ms | UI renders correctly on mobile>
+Para cada `T-NN*.md` gerado: confirmar que `head -1` retorna `---` E o frontmatter contém literalmente `status: pendente`. Se qualquer task falhar, regerar (não prosseguir com tasks malformadas — silenciar aqui é o bug original).
 
-## Riscos & Rollback
-- <risk>
-- Rollback plan: <git tag/migration revert command>
+```bash
+for f in <dirs.tasks>/T-*.md; do
+  head -1 "$f" | grep -q '^---$' || { echo "FALHA frontmatter: $f"; exit 1; }
+  grep -q '^status: pendente$' "$f" || { echo "FALHA status: $f"; exit 1; }
+done
 ```
 
 ### Phase 4 — Output a summary

package/.gos/skills/progress-tracker/SKILL.md

@@ -37,15 +37,23 @@ Formato denso, sem prosa, otimizado para tokens. Inspirado em `caveman-main` e `
 
 ```
 pendente → em-andamento → validacao → concluido
+              ↓               ↑
+        bloqueada-backend ────┘
+        (ClickUp aberto)
 ```
 
+Estado lateral `bloqueada-backend` é introduzido pelo `*execute-plan` quando a task tem `depends_on_backend:` que aponta para `## Backend pendings` ainda em aberto no ClickUp. Mantém memória do bloqueio sem regredir para `pendente`.
+
 Transições válidas:
 - `pendente → em-andamento`: livre
+- `pendente → bloqueada-backend`: livre (gate detectou no pré-flight do execute-plan)
+- `em-andamento → bloqueada-backend`: livre (executor detectou gap em runtime)
+- `bloqueada-backend → em-andamento`: requer ClickUp `concluido`/`closed` (skill checa via `mcp__clickup__clickup_get_task`)
 - `em-andamento → validacao`: requer commit preparado (não pushado)
-- `validacao → concluido`: requer aprovação humana
+- `validacao → concluido`: marcado automaticamente por `*validate-plan` quando passa em checklist + visual gate curto + diff. Manual via `*progress status T-NNN-NN concluido` aceito também.
 - `* → pendente`: rollback (libera a transição via flag `--rollback`)
 
-Transições inválidas falham com mensagem do helper `scripts/tools/plan-status.js`.
+Transições inválidas falham com mensagem da skill (state machine textual; sem helper externo).
 
 ## Subcomandos
 
@@ -67,7 +75,19 @@ Fixa o plano ativo. Ex.: `*progress set PLAN-042-checkout`. Atualiza:
 
 ### `status <task-id> <novo-status>`
 
-Muda status de uma task. Valida via state machine. Atualiza `progress.txt` (`last_done`, `next`) e o frontmatter do task file. Se a task fechar o checklist do plano, sugere `*progress status <plan-id> validacao`.
+Muda status de uma task. Valida via state machine. Atualiza:
+
+1. **Frontmatter do task file** (campo `status:` no YAML do topo). Esta e a fonte de verdade — `execute-plan`/`validate-plan` leem dali. **NAO** atualizar/criar secao `## Status` no body.
+2. `progress.txt` (`last_done`, `next`).
+
+Pre-condicao: o task file DEVE ter frontmatter YAML valido com campo `status:`. Se ausente:
+- Detectar via `head -1` != `---` OU grep `^status:` vazio.
+- Se task tem secao `## Status` no body (formato legado bugado): abortar com mensagem `task-malformada: T-NNN-NN usa formato body-status — rodar scripts/integrations/migrate-task-status.js antes de continuar`.
+- Se nao tem nem frontmatter nem `## Status`: abortar com `task-sem-status: regenerar via plan-to-tasks`.
+
+Falha de pre-condicao NAO e silenciada — se silenciar, executor segue achando que transicionou e tasks travam em `pendente` (bug original que motivou esse contrato).
+
+Se a task fechar o checklist do plano, sugere `*progress status <plan-id> validacao`.
 
 ### `compact`
 

package/.gos/skills/registry.json

@@ -22,6 +22,8 @@
     { "slug": "slack-review", "path": "skills/slack-review/SKILL.md" },
     { "slug": "stack-profiler", "path": "skills/stack-profiler/SKILL.md" },
     { "slug": "plan-blueprint", "path": "skills/plan-blueprint/SKILL.md" },
-    { "slug": "progress-tracker", "path": "skills/progress-tracker/SKILL.md" }
+    { "slug": "progress-tracker", "path": "skills/progress-tracker/SKILL.md" },
+    { "slug": "execute-plan", "path": "skills/execute-plan/SKILL.md" },
+    { "slug": "validate-plan", "path": "skills/validate-plan/SKILL.md" }
   ]
 }

package/.gos/skills/validate-plan/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: validate-plan
+description: Valida implementacao pos-execute. Para cada task em validacao, re-roda visual gate curto (anatomia + tokens), confronta diff staged contra Componentes mapeados, confere checklist do plano. Auto-marca concluido o que passa. Fecha plano quando todas as tasks fecham E backend pendings ClickUp estao concluidas.
+argument-hint: "<PLAN-NNN-slug> [NOTAS=...]"
+allowedTools: [Read, Glob, Grep, Bash, Edit, Agent, AskUserQuestion]
+sourceDocs:
+  - templates/planTemplate.md
+  - templates/taskTemplate.md
+  - playbooks/plan-creation-playbook.md
+  - skills/execute-plan/SKILL.md
+  - skills/progress-tracker/SKILL.md
+use-when:
+  - validar plano apos *execute-plan ter rodado
+  - fechar tasks em validacao -> concluido apos checklist + visual gate curto
+  - confirmar que diff staged bate com Componentes mapeados do plano
+do-not-use-for:
+  - executar tasks (use execute-plan)
+  - criar plano novo (use plan-blueprint)
+  - decompor plano em tasks (use plan-to-tasks)
+metadata:
+  category: validation
+---
+
+Voce esta executando como **Revisor de Planos** via skill `validate-plan`. Fecha o ciclo `*plan -> *execute-plan -> *validate-plan`. Ambiente recomendado: Opus 4.7 (revisor); funciona em qualquer IDE.
+
+## Input
+
+$ARGUMENTS
+
+Formato esperado:
+- `<PLAN-NNN-slug>` — id do plano (ex.: `PLAN-001-pagina-projetos-inicial`)
+- `NOTAS="..."` — opcional, contexto de QA / desvios conhecidos
+
+## Pre-requisitos (gate)
+
+1. Resolver paths via `.gos-local/plan-paths.json`. Ausente -> abortar.
+2. Localizar `<dirs.planos>/<PLAN-NNN-slug>/plan.md`. Ausente -> abortar.
+3. Ler `plan.md` por completo: frontmatter + Componentes mapeados + Plano de execucao + Checklist de aceite + Backend pendings.
+4. Listar arquivos staged: `git diff --staged --name-only`. Vazio -> warning visivel ("nenhuma alteracao staged; *execute-plan rodou?") mas NAO aborta — pode validar plano que ja foi commitado, comparando com `git log` desde `validated_at` ou `created_at`.
+5. Ler `<dirs.progress>` (progress.txt). Confirmar que `plan_active` casa com o argumento; se outro plano estiver ativo, perguntar antes de prosseguir.
+
+## Loop por task
+
+**Gate de formato (pre-loop)**: para cada `T-NN*.md` em `<dirs.planos>/<PLAN-NNN-slug>/tasks/`, confirmar `head -1 == "---"` E `grep -q '^status:'` no frontmatter. Tasks malformadas (sem frontmatter ou usando `## Status` no body) sao registradas como erro de plano: validate-plan ABORTA com mensagem `tasks-malformadas: <lista> — rodar scripts/integrations/migrate-task-status.js OU regerar via plan-to-tasks`. Isso evita o falso negativo onde tasks com codigo pronto aparecem `pendente` por bug de gerador (caso PLAN-006).
+
+Iterar tasks cujo frontmatter `status:` seja `validacao`. Tasks em outros estados (pendente, em-andamento, bloqueada-backend, concluido) sao puladas com log curto.
+
+**Diagnostico do bug PLAN-006**: se TODAS as tasks estao em `pendente` E `git diff --staged` ou `git log --since=<plan.created_at>` mostra alteracoes nos arquivos esperados, e provavel que `*execute-plan` rodou sem transicionar (bug do executor). Reportar como `executor-skipped-progress` e instruir humano: rodar `migrate-task-status.js --infer-from-diff` OU re-rodar `*execute-plan PLAN-NNN-<slug>` (que agora tem pos-condicao obrigatoria).
+
+Para cada `T-NNN-NN-*.md` em `validacao`:
+
+1. **Visual gate curto**: para cada componente do plano que a task tocou:
+   a) Localizar `<Componente>.stories.tsx` em `<dirs.storybook>`.
+   b) Comparar implementacao vs story canonica em 3 dimensoes (curto, sem refazer Figma MCP completo):
+      - **Anatomia**: ordem de slots/elementos.
+      - **Tokens**: classes Tailwind/variaveis CSS batem com DS — divergencia registrada em `## Page-level overrides` do plano NAO falha (gate confirma aplicacao do override).
+      - **Comportamentos**: para cada `interaction_target:` da task, grep do handler/estado no diff. Para cada `override_target:` da task, grep das classes/props da decisao.
+   c) Output: append em `tasks/T-NNN-NN.notes.md` na secao `## Validate run <iso>`.
+2. **Confronto diff x mapeamento**: arquivos alterados pela task estao listados em "Componentes mapeados" do plano? Arquivos fora do mapeamento -> warning (nao falha por padrao).
+3. **Checklist da task (DoD)**: ler `## Criterios de aceitacao` da task. Itens nao marcados (`[ ]`) = falha automatica.
+4. **Resultado**:
+   - **Tudo bate** -> `*progress status T-NNN-NN concluido` (auto-marca; rollback humano via `*progress status T-NNN-NN pendente --rollback` se necessario).
+   - **Falha** -> mantem `validacao`, registra divergencia em `T-NNN-NN.notes.md` secao `## Validate run <iso>`, devolve `current=` no progress apontando pra essa task.
+
+## Fechamento do plano
+
+Apos o loop:
+
+1. **Cobertura de comportamento**: ler `## Interações & Estados` em `plan.md`. Para cada bullet (slug): existe AO MENOS 1 task com `interaction_target:` apontando pra ele E status `concluido`? Bullet sem cobertura -> plano permanece em `validacao` (registrar em `T-NNN-NN.notes.md` da task mais proxima do dominio).
+2. **Cobertura de overrides**: ler `## Page-level overrides`. Cada linha com decisao (a/b/c) tem task `concluido` cobrindo? grep do `override_target:` correspondente nos frontmatter de tasks. Override sem cobertura -> plano permanece em `validacao`.
+3. **Checklist do plano**: ler `## Checklist de aceite` em `plan.md`. Itens nao marcados -> plano permanece em `validacao` mesmo se todas as tasks fecharam.
+4. **Backend pendings**: ler `## Backend pendings`. Para cada linha com `ClickUp ID`:
+   - Consultar `mcp__clickup__clickup_get_task <ID>`.
+   - Se status != `concluido`/`closed` -> bloqueio ainda ativo.
+   - Atualizar coluna `Status` da tabela com o estado atual do ClickUp.
+5. **Decisao**:
+   - Todas tasks `concluido` + cobertura de comportamento + cobertura de overrides + checklist do plano marcado + backend pendings todos `concluido` no ClickUp -> marcar `plan.md` frontmatter `validated_at: <iso>` + `*progress status PLAN-NNN-<slug> concluido`.
+   - Caso contrario -> manter `validacao`, listar bloqueios.
+6. **Push**: NAO. Commit ja foi preparado por `*execute-plan`. Push e ato consciente humano (`git push`).
+
+## Saida final ao usuario
+
+Resumo em 4 blocos:
+
+```
+[validate-plan] PLAN-NNN-<slug>
+
+tasks concluidas:   <N>  (T-..., T-...)
+tasks pendentes:    <M>  (T-..., T-...)
+bloqueada-backend:  <K>  (T-...:CU-..., ...)
+backend pendings:   <X>  abertas no ClickUp / <Y> concluidas
+
+plano: <concluido | validacao>
+proximo passo: <git push | resolver bloqueios | re-rodar visual gate em T-...>
+```
+
+## Diferenca x execute-plan (anti-overlap)
+
+- `execute-plan`: visual gate completo (5 dimensoes + Figma MCP arvore), pre-flight smoke (screenshot vs frame), executa codigo via Agent tool, opera estado `em-andamento`.
+- `validate-plan`: visual gate curto (3 dimensoes — anatomia, tokens, comportamentos — sem Figma MCP completo), nao executa codigo, opera estado `validacao -> concluido`, valida cobertura de `interaction_target` e `override_target` no plano. Reaproveita `notes.md` em secao separada `## Validate run <iso>`.
+
+Se `validate-plan` detectar que uma task em `validacao` claramente NAO foi implementada (diff staged nao toca os arquivos esperados), nao reabre execucao — devolve falha clara e instrui usuario a rodar `*execute-plan PLAN-NNN-<slug> --task T-NNN-NN`.
+
+## Regras criticas
+
+- **Auto-conclusao e default**: tudo que passa em checklist + visual gate curto + diff vira `concluido` automaticamente. Rollback humano sempre disponivel.
+- **Sem push automatico**: commit ja preparado pelo `*execute-plan`, push e manual.
+- **State machine respeitada**: tasks `bloqueada-backend` ficam intocadas — backend tem que fechar primeiro.
+- **Backend pendings via ClickUp MCP**: se MCP indisponivel, registra warning e mantem plano em `validacao` ate humano confirmar manualmente.
+
+## Model guidance
+
+| Escopo | Modelo |
+|--------|--------|
+| Validacao curta de plano com poucas tasks | `sonnet` |
+| Plano grande (10+ tasks, varios componentes) | `opus` |
+| Visual gate curto (2 dimensoes, sem Figma MCP) | inherit |
+
+## Instructions
+
+1. NUNCA pular checklist do plano — itens nao marcados bloqueiam fechamento.
+2. NUNCA marcar `concluido` sem visual gate curto rodado e gravado em `T-NNN-NN.notes.md`.
+3. Backend pendings via ClickUp MCP sao vinculantes — plano so fecha quando todos `concluido`.
+4. Resolver TODOS os paths via `plan-paths.json`.
+5. Output final: 4-block summary + comando exato de proximo passo (push manual, ou comandos para resolver bloqueios).