ganbatte-os 0.2.34 → 0.2.36

package/.gos/agents/profiles/ganbatte-os-master.md

@@ -99,6 +99,7 @@ comprehension_gate:
     step_0_58_knowledge: "On *plan: index <PROJETO>/docs/regras-de-negocio/ and <PROJETO>/docs/postman/ (when present). Register inventory in progress.txt under '## Knowledge mapped — PLAN-NNN'. Ausência não bloqueia (apenas Storybook bloqueia)."
     step_0_59_backend_gaps: "On *plan: detected backend gaps (endpoint não existe no Postman, RLS incompleto, migration ausente para o shape exigido) → criar task ClickUp via mcp__clickup__clickup_create_task, assignee Douglas Oliveira (112010775) salvo override ASSIGNEE no prompt. Título: '[Backend] PLAN-NNN: <gap>'. Registrar IDs em progress.txt e plan.md (## Backend pendings). Flag --skip-clickup desliga."
     step_0_6_progress: "If progress.txt exists at the configured path: read it for active plan/task context (memória L1)."
+    step_1_2_interactions: "On *plan: detect if a tela tem table-clicável/drawer/modal/popup. Heurística: (a) Figma MCP frames com layer names contendo Drawer|Modal|Dialog|Popup|Sheet; (b) NOTAS menciona drawer/modal/popup/clickable row; (c) tela existente em dirs.app com componente equivalente (page.tsx que importa Drawer/Dialog). Se sim E INTERACOES ausente no input: BLOQUEAR plan-blueprint e disparar AskUserQuestion estruturado pedindo lista de interações com 3 exemplos pré-preenchidos (clickable row, submit assíncrono, filtro). Resposta vira entrada da Fase 1.4 do plan-blueprint (`## Interações & Estados`). Telas simples (form linear, lista read-only, página estática) NÃO acionam o bloqueio."
     step_1_document: "State what exists (current state, patterns, constraints) in factual terms"
     step_2_assess: "Determine which agent/skill/workflow is appropriate based on evidence, not assumption"
     step_3_delegate: "Route with context summary so the target has full picture"
@@ -203,13 +204,30 @@ routing_matrix:
   plan_creation:
     triggers: [plan, plano, screen plan, tela, criar plano, blueprint, plano de tela]
     target: skill:plan-blueprint
-    pre_action: Validate docs/stack.md exists; if not, dispatch stack-profiler first
+    pre_action: Validate docs/stack.md exists; if not, dispatch stack-profiler first. Run step_1_2_interactions — block + AskUserQuestion when tela tem table-clicável/drawer/modal/popup E INTERACOES ausente.
+    post_action: |
+      OBRIGATÓRIO em sequência ANTES de devolver "plano criado":
+      1. dispatch skill:plan-to-tasks apontando plan.md recém-criado (gera T-NN*.md no tasks/).
+      2. Bash: `node .gos/scripts/integrations/check-plan.js <plan-dir>` (gate determinístico).
+      3. Se exit != 0: regerar plan-to-tasks 1x e re-rodar check-plan. Se persistir, ABORTAR
+         e devolver a saída literal do check-plan ao usuário com instrução para migrate-task-status.js.
+      `*plan` NUNCA termina com tasks/ vazio. NUNCA termina sem exit 0 do check-plan.
     notes: |
+      *plan é operação ATÔMICA: {plan.md + context.md + tasks/T-NN.md (TODAS) + progress.txt}.
+      Plano sem tasks = falha — plan-blueprint deve invocar plan-to-tasks E rodar o gate
+      determinístico `node .gos/scripts/integrations/check-plan.js <plan-dir>` como ÚLTIMA
+      ação. Exit != 0 bloqueia o "plano criado" — sem barreira no LLM (script roda fora).
+      Bug histórico: tasks geradas sem frontmatter ficavam travadas em pendente mesmo após
+      *execute-plan rodar código (PLAN-006). Planos preexistentes: rodar migrate-task-status.js.
+
       1 tela = 1 plano. OBJETIVO obrigatório no prompt:
         - implantacao  → criar do zero (fluxo padrão)
         - correcao     → cirúrgico, diff vs Storybook, 1 task por componente
         - refactor     → implica --allow-arch-change + ADR
       Auto-resolve PROJETO/WORK_BRANCH/BUSINESS_RULES/POSTMAN no comprehension gate.
+      INTERACOES obrigatório quando tela tem table-clicável/drawer/modal/popup — gos-master bloqueia
+      e abre AskUserQuestion se ausente. Plano captura comportamentos (Fase 1.4 do plan-blueprint)
+      e page-level overrides (Figma da página > Storybook canônico em conflito visual).
       Backend gaps → tasks ClickUp automáticas pro Douglas (--skip-clickup desliga).
 
   progress_tracking:
@@ -220,11 +238,28 @@ routing_matrix:
   execute_plan:
     triggers: [execute, executar plano, run plan, "*execute-plan", execute plan, executar PLAN]
     target: skill:execute-plan
-    pre_action: Validate PLAN-NNN-<slug>/plan.md exists; load stack.md; index dirs.storybook stories
+    pre_action: Validate PLAN-NNN-<slug>/plan.md exists; load stack.md; index dirs.storybook stories. Verificar que cada T-NN.md tem frontmatter com `status:` — task malformada ABORTA com instrução para rodar migrate-task-status.js.
     notes: |
       Comando primário do ambiente Codex IDE Extension.
-      Ciclo Opus(plan) → Codex(execute). Roda task-a-task com state machine
-      e visual gate obrigatório contra Storybook canônico antes de validacao.
+      Ciclo Opus(plan) → Codex(execute) → Opus(validate). Roda task-a-task com state machine
+      e visual gate obrigatório (5 dimensões: anatomia, tokens, variants, densidade, comportamentos)
+      contra Storybook canônico antes de validacao. Pre-flight smoke compara screenshot da página
+      vs Figma frame antes da T-01 (gera tasks T-000-XX para gaps grandes).
+      Non-blocking em backend gaps: tasks com depends_on_backend não-resolvido viram
+      bloqueada-backend (ClickUp aberto pro Douglas), demais seguem.
+      Transições de status são VINCULANTES com pós-condição: cada task DEVE sair de pendente
+      antes da próxima — se o executor não chamar progress-tracker, abortar (bug PLAN-006).
+
+  validate_plan:
+    triggers: [validate, validar plano, "*validate-plan", validate plan, revisar plano, plano implementado]
+    target: skill:validate-plan
+    pre_action: Validate PLAN-NNN-<slug>/plan.md exists; load progress.txt
+    notes: |
+      Turn pós-execute. Para cada task em validacao, re-roda visual gate curto
+      (anatomia + tokens, sem refazer Figma MCP), confronta diff staged vs
+      Componentes mapeados, confere checklist do plano e da task.
+      Auto-marca concluido o que passa. Fecha plano quando todas tasks fecham
+      E backend pendings ClickUp estão concluídas. NÃO dá push.
 
   product_decisions:
     triggers: [PRD, requirements, product decision, scope, feature priority]
@@ -313,8 +348,11 @@ commands:
     args: "[init|show|set <plan>|status <task> <novo-status>|compact|read]"
     description: Gerencia progress.txt (memória L1) e state machine de status
   - name: execute-plan
-    args: "<PLAN-NNN-slug> [--task T-NNN-NN] [--skip-visual-gate]"
-    description: Executa plano task-a-task com visual gate obrigatório (comando primário do Codex IDE)
+    args: "<PLAN-NNN-slug> [--task T-NNN-NN] [--skip-visual-gate] [--skip-clickup]"
+    description: Executa plano task-a-task com visual gate obrigatório, non-blocking em backend gaps (Codex IDE)
+  - name: validate-plan
+    args: "<PLAN-NNN-slug> [NOTAS=...]"
+    description: Valida plano pós-execute; auto-marca concluido tasks que passam em checklist + visual gate curto + diff (Opus revisor)
 
   # Quality
   - name: check
@@ -351,7 +389,7 @@ available_squads:
   - name: git-operations
     purpose: SSH setup, quality gate, safe commit+push
 
-# ─── AVAILABLE SKILLS (19) ────────────────────────────────────
+# ─── AVAILABLE SKILLS (20) ────────────────────────────────────
 available_skills:
   - design-to-code
   - figma-implement-design
@@ -372,6 +410,7 @@ available_skills:
   - plan-blueprint
   - progress-tracker
   - execute-plan
+  - validate-plan
 
 # ─── PLAYBOOKS ────────────────────────────────────────────────
 available_playbooks:
@@ -474,7 +513,8 @@ security:
 
 - `*stack [refresh|show|drift]` - Mantém docs/stack.md
 - `*plan <tela|figma-url|descrição>` - Cria plano por tela (Opus, planejamento)
-- `*execute-plan <PLAN-NNN-slug>` - Executa plano com visual gate (Codex IDE, execução)
+- `*execute-plan <PLAN-NNN-slug>` - Executa plano com visual gate, non-blocking em backend gaps (Codex IDE, execução)
+- `*validate-plan <PLAN-NNN-slug>` - Valida plano pós-execute; auto-marca concluido (Opus, revisor)
 - `*progress [show|set|status|compact]` - Gerencia progress.txt (L1)
 
 **Framework:**

package/.gos/libraries/frontend/state-persistence-patterns.md

@@ -0,0 +1,300 @@
+# State Persistence Patterns (FOUC Zero)
+
+Reference library for persisting UI state across reloads in SSR/Edge frameworks (Next.js App Router, Remix, SvelteKit) **without** flash of incorrect content (FOUC) or hydration mismatch.
+
+This library is the positive counterpart to `content/ai-writing-patterns.md`: instead of cataloging anti-patterns to avoid, it codifies **patterns to apply** for any UI state that survives reload.
+
+---
+
+## When this applies
+
+State is "persisted UI state" if **all** of the following are true:
+
+1. It survives page reloads (cookie, localStorage, URL, server session).
+2. It affects the **first paint** of the layout (sidebar collapsed/expanded, theme, density, locale, RTL/LTR, font-size preset).
+3. It has a default value used when the persisted value is missing.
+
+If state is client-only and **does not** affect the first paint (form drafts, in-page panels not visible at load, ephemeral preferences) — these patterns are not required; localStorage + `useEffect` is fine.
+
+---
+
+## The core problem: client-only persistence creates FOUC
+
+A naive implementation reads the persisted value on the client *after* hydration:
+
+```tsx
+// ANTI-PATTERN — produces visible flash
+function SidebarProvider({ defaultOpen = true, children }) {
+  const [open, setOpen] = useState(defaultOpen)
+
+  useEffect(() => {
+    const saved = document.cookie.match(/sidebar_state=(\w+)/)?.[1]
+    if (saved === "false") setOpen(false)   // flash: SSR rendered open, this closes it
+  }, [])
+
+  return <Context.Provider value={{ open }}>{children}</Context.Provider>
+}
+```
+
+Sequence that produces the flash:
+
+1. **SSR**: HTML is rendered with `defaultOpen=true` (server has no access to client state).
+2. **First paint**: browser shows sidebar **open**.
+3. **Hydration**: React mounts with `open=true`.
+4. **`useEffect` fires**: reads cookie `false` → `setOpen(false)` → re-render → sidebar collapses.
+
+The flash is 16–200ms depending on network/CPU. On slow connections it is painful UX.
+
+---
+
+## Pattern A — Server-read cookie + `defaultX` injection (canonical)
+
+**When to use**: any state where the persistence medium is a **cookie** and the framework supports reading cookies in Server Components.
+
+**Next.js App Router (canonical)**:
+
+```tsx
+// app-shell.tsx — Server Component
+import { cookies } from "next/headers"
+import { SidebarProvider } from "@/components/ui/sidebar"
+
+export async function AppShell({ children }: { children: React.ReactNode }) {
+  const cookieStore = await cookies()                            // Next 15+ async; Next 14 sync
+  const saved = cookieStore.get("sidebar_state")?.value
+  const defaultOpen = saved === undefined ? true : saved === "true"
+
+  return <SidebarProvider defaultOpen={defaultOpen}>{children}</SidebarProvider>
+}
+```
+
+```tsx
+// sidebar.tsx — Client Component
+"use client"
+
+export function SidebarProvider({ defaultOpen = true, children }) {
+  const [open, _setOpen] = useState(defaultOpen)                 // hydrates with correct value
+
+  const setOpen = useCallback((next: boolean) => {
+    _setOpen(next)
+    document.cookie = `sidebar_state=${next}; path=/; max-age=${60 * 60 * 24 * 7}`
+  }, [])
+
+  return <Context.Provider value={{ open, setOpen }}>{children}</Context.Provider>
+}
+```
+
+**Why this works**:
+- Server reads cookie → SSR HTML reflects the persisted state.
+- First paint already correct.
+- Hydration uses `defaultOpen` from server → no client-side correction needed.
+- `useEffect` is **not used for initial state** — only `setOpen` writes the cookie when the user toggles.
+
+**Cost**: `cookies()` forces dynamic rendering of the page that uses it. Acceptable for authenticated dashboards (already dynamic). For static pages, use Pattern C.
+
+---
+
+## Pattern B — `headers()` for derived state (locale, theme by system pref proxy)
+
+When the state can be derived from a request header (e.g., `Accept-Language`, `Sec-CH-Prefers-Color-Scheme`), read it server-side and inject as default:
+
+```tsx
+import { headers } from "next/headers"
+
+export async function ThemeShell({ children }) {
+  const h = await headers()
+  const prefersDark = h.get("sec-ch-prefers-color-scheme") === "dark"
+  return <ThemeProvider defaultTheme={prefersDark ? "dark" : "light"}>{children}</ThemeProvider>
+}
+```
+
+Use this **in addition to** Pattern A: server reads cookie first; if missing, derives from headers; client toggles persist back to cookie.
+
+---
+
+## Pattern C — Inline blocking script for static pages (last resort)
+
+When the page **must** stay static (cannot opt into dynamic rendering) but still needs FOUC-free persisted state, use a small synchronous script in `<head>` that sets a class/attribute on `<html>` **before** the first paint:
+
+```tsx
+// app/layout.tsx
+import Script from "next/script"
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="pt-BR" suppressHydrationWarning>
+      <head>
+        <Script id="set-sidebar-state" strategy="beforeInteractive">
+          {`(function(){try{var m=document.cookie.match(/sidebar_state=(\\w+)/);
+            if(m&&m[1]==="false"){document.documentElement.dataset.sidebar="collapsed"}}catch(e){}})()`}
+        </Script>
+      </head>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+Then CSS reads the attribute:
+
+```css
+[data-sidebar="collapsed"] aside { width: 56px; }
+```
+
+**Caveats**:
+- Adds blocking JS to critical path (~1KB).
+- CSP must allow the inline script (or extract to external file with hash).
+- Only use when Pattern A is impossible (truly static pages).
+
+This is what `next-themes` does for theme persistence on static pages.
+
+---
+
+## Pattern D — URL state (no FOUC by definition)
+
+For state that should be **shareable** (filters, tabs, pagination), persist in the URL search params. The server reads `searchParams` on render, so first paint is always correct:
+
+```tsx
+// page.tsx — Server Component
+export default async function Page({ searchParams }) {
+  const params = await searchParams
+  const view = params.view ?? "grid"
+  return <Layout defaultView={view}>...</Layout>
+}
+```
+
+This trades persistence-across-sessions (cookies persist; URL is per-tab) for shareability and bookmarkability. Use both: URL for view state, cookie for chrome (sidebar/theme).
+
+---
+
+## Decision tree
+
+```
+Does the state affect first paint?
+├── No  → localStorage + useEffect is fine.
+└── Yes → Is it shareable / bookmarkable?
+         ├── Yes → Pattern D (URL search params).
+         └── No  → Is the route already dynamic?
+                  ├── Yes → Pattern A (cookies() in Server Component).
+                  └── No  → Can the route opt into dynamic rendering?
+                           ├── Yes → Pattern A; route becomes dynamic.
+                           └── No  → Pattern C (blocking script).
+```
+
+---
+
+## Anti-patterns (catalog)
+
+### A1. `useEffect` to read persisted state and `setState`
+
+```tsx
+// BAD
+useEffect(() => {
+  const saved = localStorage.getItem("theme")
+  if (saved) setTheme(saved)
+}, [])
+```
+
+**Why bad**: SSR renders default; client corrects after hydration → flash.
+
+**Fix**: Pattern A or C.
+
+### A2. Conditional render that hides until hydrated
+
+```tsx
+// BAD
+const [hydrated, setHydrated] = useState(false)
+useEffect(() => setHydrated(true), [])
+if (!hydrated) return null     // layout shift on hydration
+return <Sidebar open={open} />
+```
+
+**Why bad**: layout shift (CLS hit), accessibility regression (sidebar invisible to screen readers initially).
+
+**Fix**: Pattern A or C.
+
+### A3. `suppressHydrationWarning` to mask the mismatch
+
+```tsx
+// BAD
+<aside suppressHydrationWarning data-state={open ? "open" : "closed"}>
+```
+
+**Why bad**: hides the symptom, not the cause. The actual visual flash still happens.
+
+**Fix**: solve the root cause with Pattern A. Use `suppressHydrationWarning` only on `<html>` for theme (where the script in Pattern C legitimately mutates the attribute before React hydrates).
+
+### A4. Cookie set in client without server read
+
+```tsx
+// BAD — server cannot read what only the client wrote
+function setOpen(next) {
+  document.cookie = `sidebar_state=${next}`
+  setOpenState(next)
+}
+// And the server never reads "sidebar_state" → flash on every reload.
+```
+
+**Why bad**: persistence works (cookie is sent on next request), but the server doesn't use it — the loop is incomplete.
+
+**Fix**: complete the loop — server reads in Pattern A.
+
+### A5. localStorage for layout-affecting state
+
+```tsx
+// BAD for state affecting first paint
+localStorage.setItem("sidebar_state", "false")
+```
+
+**Why bad**: localStorage is **client-only** by definition; no server-side reading possible. Inevitable flash.
+
+**Fix**: migrate to cookie (Pattern A) or accept blocking script (Pattern C). localStorage is fine for client-only state that doesn't affect first paint.
+
+### A6. Default state assumed identical for all users
+
+```tsx
+// BAD when users have different defaults (locale, timezone, RTL)
+<App defaultLocale="en" />
+```
+
+**Why bad**: ignores `Accept-Language`; first paint is "wrong" for half the users until client correction.
+
+**Fix**: Pattern B (read header) + Pattern A (override with user-saved cookie).
+
+---
+
+## Checklist for any persisted UI state
+
+Before merging a feature that persists state:
+
+- [ ] Does the state affect first paint? If yes:
+  - [ ] Is the persistence medium readable on the server (cookie, header)? If no, migrate it.
+  - [ ] Does the Server Component / loader pass the persisted value as `defaultX` to the Client Component? If no, add it.
+  - [ ] Is there a `useEffect` reading the persisted value to update state? If yes, **remove it** (Pattern A makes it redundant).
+- [ ] Does the toggle UI write to the same persistence medium the server reads? (Cookie path/expiry must match.)
+- [ ] Tested on Slow 3G: zero flash on reload?
+- [ ] Tested in incognito (no cookie): falls back to default cleanly?
+- [ ] Tested on mobile (different state model often required).
+
+---
+
+## Real incidents this library prevents
+
+- **Sidebar flash open→closed on reload** (Fractus 2026-05-04, T-51): cookie persisted but read in `useEffect`; fix moved read to `cookies()` in Server Component.
+- **Theme flash light→dark on reload** (common pre-`next-themes`): solved by Pattern C blocking script. `next-themes` automates it.
+- **Wrong locale flash for non-English users**: solved by Pattern B reading `Accept-Language`.
+
+---
+
+## References
+
+- Next.js docs: [`cookies()`](https://nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://nextjs.org/docs/app/api-reference/functions/headers).
+- shadcn/ui sidebar: [persistence pattern](https://ui.shadcn.com/docs/components/sidebar) — uses Pattern A by default.
+- `next-themes`: source for Pattern C reference implementation.
+- React docs: [hydration mismatches](https://react.dev/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html).
+
+---
+
+## Cross-references in this framework
+
+- Anti-patterns of writing/content: `.gos/libraries/content/ai-writing-patterns.md` (analogous catalog format).
+- (Add `.gos/libraries/frontend/nextjs-patterns.md` and `react-patterns.md` here when ported.)

package/.gos/playbooks/plan-creation-playbook.md

@@ -41,26 +41,29 @@ Se houver drift, decidir entre:
 ```
 *plan <tela>
 
-OBJETIVO = implantacao | correcao | refactor   # obrigatório
-FIGMA    = <url-frame>
-FIGMA+   = [<url-comp>, ...]                   # opcional
-NOTAS    = """<prosa livre>"""                 # opcional
-ASSIGNEE = <user-id>                           # opcional, default 112010775 (Douglas)
+OBJETIVO   = implantacao | correcao | refactor   # obrigatório
+FIGMA      = <url-frame>
+FIGMA+     = [<url-comp>, ...]                   # opcional
+INTERACOES = """<lista estruturada — obrigatório quando tela tem table-clicável/drawer/modal/popup>"""
+NOTAS      = """<prosa livre>"""                 # opcional
+ASSIGNEE   = <user-id>                           # opcional, default 112010775 (Douglas)
 ```
 
 `gos-master` resolve no comprehension gate (não pedir ao usuário):
 - `PROJETO` (cwd, ou `~/.claude/.gos-state/last-project.json`)
 - `WORK_BRANCH` (`dev` para app, `feat/storybook` quando em Storybook)
 - Indexação de `<PROJETO>/docs/regras-de-negocio/` e `docs/postman/` (registrada em `progress.txt`)
+- **Step 1.2 — Coleta de comportamentos**: detecta se tela tem table-clicável/drawer/modal/popup. Sim E `INTERACOES` ausente → bloqueia + dispara `AskUserQuestion` estruturado pedindo as interações (3 exemplos pré-preenchidos). Telas simples (form linear, lista read-only) não acionam.
 
 `plan-blueprint` executa:
 1. Fase 1 — Mapeamento Visual & Componentização
+   1.4 Comportamentos & Overrides — `## Interações & Estados` + `## Page-level overrides` no plano
 2. Fase 2 — Aderência à Stack (sem redefinir arquitetura)
 2.5 Fase 2.5 — Backend gaps → criar tasks ClickUp pro Douglas (`--skip-clickup` desliga)
-3. Fase 3 — Plano de Execução
+3. Fase 3 — Plano de Execução (gera tasks com `interaction_target` e `override_target` para cobrir comportamentos e overrides)
 
 Saídas:
-- `<dirs.planos>/PLAN-NNN-<slug>/plan.md` (com seções `## Backend pendings` e `## Knowledge mapped`)
+- `<dirs.planos>/PLAN-NNN-<slug>/plan.md` (com seções `## Backend pendings`, `## Knowledge mapped`, `## Interações & Estados`, `## Page-level overrides`)
 - `<dirs.planos>/PLAN-NNN-<slug>/context.md`
 - `<dirs.planos>/PLAN-NNN-<slug>/tasks/T-NNN-NN-*.md`
 - `progress.txt` atualizado com plano ativo + inventário de knowledge + backend pendings
@@ -80,7 +83,10 @@ Se aprovado, prosseguir. Caso contrário: ajustar manualmente ou rerodar `*plan`
 *execute-plan PLAN-NNN-<slug>
 ```
 
-A skill `execute-plan` resolve `dirs.storybook`, indexa `.stories.tsx` disponíveis e confronta cada componente da tabela "Componentes mapeados" do plano. Componente sem story → bloqueia e propõe task de criação ANTES das tasks de implementação.
+A skill `execute-plan` faz dois pre-flights antes da T-01:
+
+1. **Stories disponíveis**: resolve `dirs.storybook`, indexa `.stories.tsx`, confronta cada componente da tabela "Componentes mapeados". Componente sem story → bloqueia e propõe task de criação ANTES das tasks de implementação.
+2. **Visual smoke** (quando Storybook story-da-página OU Playwright MCP disponível): renderiza a página com seed e compara screenshot vs frame Figma em 3 dimensões básicas (seções presentes, layout grosseiro, cores primárias). Gaps grandes viram tasks `T-000-XX` com `priority: P0` antes do loop. Sem Storybook full-page nem Playwright MCP: skip com warning. Esse pre-flight evita o padrão PLAN-005 (gaps grandes descobertos via 26 rodadas de feedback no fim).
 
 > Ambiente recomendado: **Codex IDE Extension** (executor). O `*plan` da etapa 2 roda em Opus 4.7 (planejador). Adapter Codex é gerado por `npm run sync:ides`.
 
@@ -91,28 +97,38 @@ A skill `execute-plan` resolve `dirs.storybook`, indexa `.stories.tsx` disponív
 1. `*progress status T-NNN-NN em-andamento` (state machine).
 2. Despacha agent (`labels: [agent:<slug>]`, default `dev`) para implementar.
 3. **Visual gate** antes de marcar `validacao`:
-   - Compara cada componente alterado com `<Componente>.stories.tsx` em 4 dimensões (anatomia, tokens, variants, densidade).
+   - Compara cada componente alterado com `<Componente>.stories.tsx` em 5 dimensões (anatomia, tokens, variants, densidade, comportamentos). Tokens divergentes registrados em `## Page-level overrides` do plano não falham — gate confirma aplicação do override.
+   - Comportamentos: cada `interaction_target:` declarado na task tem handler/estado observável no diff; cada `override_target:` tem classes/props da decisão (a/b/c) presentes.
    - Cruza JSX da tela com Figma MCP (árvore vs hierarquia).
    - Falha → task volta a `em-andamento` com diff em `tasks/T-NNN-NN.notes.md`.
 4. Sucesso → `*progress status T-NNN-NN validacao`.
 
 Para rodar uma task específica fora do loop: `*execute-plan PLAN-NNN-<slug> --task T-NNN-NN`.
 
-### 5. Validação
+### 4.5. Validação pós-execute
 
-Quando todas as tasks do plano estiverem `validacao` e o checklist do plano estiver completo:
+Após `*execute-plan` retornar (com tasks em `validacao` e/ou `bloqueada-backend`), rodar:
 
 ```
-*progress status PLAN-NNN-<slug> validacao
+*validate-plan PLAN-NNN-<slug>
+
+NOTAS = """<opcional — desvios conhecidos, contexto de QA>"""
 ```
 
-Validação humana + QA. Se aprovado:
+Skill `validate-plan` (Opus, revisor):
+- Para cada task em `validacao`: re-roda visual gate curto (anatomia + tokens + comportamentos), confronta `git diff --staged` vs Componentes mapeados, confere checklist da task e `interaction_target`/`override_target`. Tudo bate → auto-marca `concluido`. Falha → mantém `validacao` com nota.
+- Para o plano: cobertura de comportamento (`## Interações & Estados`) + cobertura de overrides (`## Page-level overrides`) + checklist do plano + backend pendings ClickUp todos `concluido` → marca `validated_at:` no plan.md + `*progress status PLAN-NNN-<slug> concluido`. Senão → mantém em `validacao`.
+- Tasks `bloqueada-backend` ficam intocadas — backend tem que fechar primeiro.
+
+### 5. Push manual e fechamento
+
+`validate-plan` NÃO dá push. Quando o plano fecha 100%:
 
 ```
-*progress status PLAN-NNN-<slug> concluido
+git push
 ```
 
-(Status `concluido` SOMENTE após validação. Antes disso, qualquer task/plano fica em `validacao`.)
+Push é ato consciente do humano. Tasks `bloqueada-backend` aguardam ClickUp fechar — quando isso acontece, rodar `*progress status T-NNN-NN em-andamento` (state machine valida ClickUp via MCP) e voltar pra etapa 4.
 
 ### 6. Commit & resumo
 
@@ -140,6 +156,7 @@ Validação humana + QA. Se aprovado:
 - `stack-profiler` — produz/mantém `stack.md`
 - `plan-blueprint` — cria plano por tela (Opus, planejamento)
 - `plan-to-tasks` — decompõe plano em tasks (chamada automaticamente)
-- `execute-plan` — executa plano com visual gate (Codex IDE, execução)
-- `progress-tracker` — gerencia `progress.txt`
+- `execute-plan` — executa plano com visual gate, non-blocking em backend gaps (Codex IDE, execução)
+- `validate-plan` — valida plano pós-execute, auto-marca concluido (Opus, revisor)
+- `progress-tracker` — gerencia `progress.txt` + state machine (incluindo `bloqueada-backend`)
 - `clickup` — sync opcional para tracking externo (não obrigatório)

package/.gos/scripts/integrations/check-plan.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * check-plan.js — barreira deterministica de criacao de plano.
+ *
+ * Roda como ULTIMA acao obrigatoria do *plan (apos plan-blueprint +
+ * plan-to-tasks). Valida que o plano e usavel pelo *execute-plan e
+ * *validate-plan. Falha = *plan nao terminou — usuario ve erro, nao
+ * "plano criado" ilusorio.
+ *
+ * Uso:
+ *   node check-plan.js <plan-dir>
+ *
+ * Verificacoes:
+ * 1. plan.md existe e tem frontmatter YAML.
+ * 2. context.md existe.
+ * 3. tasks/ existe e contem >= 1 T-NN*.md.
+ * 4. Cada T-NN*.md: head -1 == "---" E frontmatter contem `status: pendente`
+ *    E `id:`, `plan_id:`, `seq:`, `title:`.
+ * 5. Nenhum T-NN*.md tem secao `## Status` no body (formato bugado legado).
+ *
+ * Exit code:
+ *   0 = plano valido, usavel pelo pipeline
+ *   1 = falha — mensagem aponta exatamente o que esta errado
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const planDir = process.argv[2];
+
+if (!planDir) {
+  console.error('uso: check-plan.js <plan-dir>');
+  process.exit(1);
+}
+
+if (!fs.existsSync(planDir)) {
+  console.error(`[check-plan] FALHA: plan-dir nao existe: ${planDir}`);
+  process.exit(1);
+}
+
+const errors = [];
+const warnings = [];
+
+const planFile = path.join(planDir, 'plan.md');
+const contextFile = path.join(planDir, 'context.md');
+const tasksDir = path.join(planDir, 'tasks');
+
+if (!fs.existsSync(planFile)) {
+  errors.push(`plan.md ausente em ${planDir}`);
+} else {
+  const plan = fs.readFileSync(planFile, 'utf8');
+  if (!plan.startsWith('---\n')) {
+    errors.push(`plan.md sem frontmatter YAML (head -1 != "---")`);
+  }
+}
+
+if (!fs.existsSync(contextFile)) {
+  warnings.push(`context.md ausente — recomendado, nao bloqueia`);
+}
+
+if (!fs.existsSync(tasksDir)) {
+  errors.push(`tasks/ ausente em ${planDir} — *plan deve invocar plan-to-tasks`);
+} else {
+  const taskFiles = fs.readdirSync(tasksDir)
+    .filter((f) => /^T-\d+.*\.md$/.test(f))
+    .map((f) => path.join(tasksDir, f));
+
+  if (taskFiles.length === 0) {
+    errors.push(`tasks/ vazio — nenhum T-NN*.md encontrado`);
+  }
+
+  for (const file of taskFiles) {
+    const rel = path.relative(planDir, file);
+    const raw = fs.readFileSync(file, 'utf8');
+
+    if (!raw.startsWith('---\n')) {
+      errors.push(`${rel}: sem frontmatter YAML (head -1 != "---")`);
+      continue;
+    }
+
+    const fmEnd = raw.indexOf('\n---', 4);
+    if (fmEnd === -1) {
+      errors.push(`${rel}: frontmatter aberto sem fechar ("---" final ausente)`);
+      continue;
+    }
+    const frontmatter = raw.slice(4, fmEnd);
+    const body = raw.slice(fmEnd + 4);
+
+    const required = ['id', 'plan_id', 'seq', 'title', 'status'];
+    for (const key of required) {
+      if (!new RegExp(`^${key}:\\s*\\S`, 'm').test(frontmatter)) {
+        errors.push(`${rel}: frontmatter sem campo \`${key}:\``);
+      }
+    }
+
+    if (!/^status:\s*pendente\s*$/m.test(frontmatter)) {
+      errors.push(`${rel}: frontmatter status: deve ser exatamente "pendente" no plano recem-criado`);
+    }
+
+    if (/^## Status\s*$/m.test(body)) {
+      errors.push(`${rel}: contem secao "## Status" no body (formato legado bugado) — rodar migrate-task-status.js`);
+    }
+  }
+}
+
+if (warnings.length) {
+  for (const w of warnings) console.error(`[check-plan] aviso: ${w}`);
+}
+
+if (errors.length) {
+  console.error(`\n[check-plan] FALHA — plano NAO usavel pelo *execute-plan:\n`);
+  for (const e of errors) console.error(`  - ${e}`);
+  console.error(`\nproximo passo: regerar tasks via plan-to-tasks OU rodar migrate-task-status.js ${planDir}`);
+  process.exit(1);
+}
+
+const taskCount = fs.readdirSync(tasksDir)
+  .filter((f) => /^T-\d+.*\.md$/.test(f)).length;
+console.log(`[check-plan] OK — ${planDir}: plan.md + context.md + ${taskCount} tasks (todas com frontmatter status: pendente).`);
+process.exit(0);