Merge pull request #320 from fsolla/cursor/2287a5c2

docs(plan-issue): canvas UI draft at gate when UI changes

.cursor/skills/plan-issue/SKILL.md

@@ -3,9 +3,11 @@ name: plan-issue
 description: >-
   Transforma ideias humanas em Issues GitHub + planos de intenção em
   docs/plans/ (persona, fluxo, objetivo, direção suave no código — sem
-  decisões duras de engenharia). Divide o pedido nas menores tarefas que
-  ainda fazem sentido. Use quando o usuário pedir /plan-issue, planejar
-  features, fatiar um pedido em Issues, ou registrar trabalho novo na fila.
+  decisões duras de engenharia). Se o item muda UI, apresenta no gate um
+  Cursor canvas com rascunho visual UI/UX. Divide o pedido nas menores
+  tarefas que ainda fazem sentido. Use quando o usuário pedir /plan-issue,
+  planejar features, fatiar um pedido em Issues, ou registrar trabalho novo
+  na fila.
 disable-model-invocation: true
 ---
 
@@ -33,6 +35,8 @@ rascunho local (Issue: —)
 4. **Promote só depois do plano em `main`.** Nunca flipar para `ready` com o PR ainda aberto — isso recria a race de claim. Caminhos: (A) agente no fim do Passo 6 após merge; (B) Action determinística no merge que lê `Related #N` (OPS18). Ambos idempotentes.
 5. **Planos de Issues `in-progress` / `done` / `in-prod` são imutáveis.** Não editar `docs/plans/<slug>.md` nem o body de intenção dessas Issues. Refino → **plano + Issue novos** (sucessor; `depends` no pai se fizer sentido). Enquanto a Issue ainda é só `blocked`/`ready` (sem claim), editar o mesmo plano ainda é barato.
 
+**Canvas UI (obrigatório se muda UI):** itens com superfície Impeccable **B / C / D** (ou qualquer mudança do que o usuário vê/toca) devem ter um **Cursor canvas** de rascunho UI/UX no gate — ver [ui-draft-canvas.md](ui-draft-canvas.md). Classe A / sem UI → sem canvas.
+
 ## Divisão com as skills de execução
 
 | Skill | Papel |
@@ -41,7 +45,7 @@ rascunho local (Issue: —)
 | **`work-issue`** | Humano supervisiona: claim → plano de **implementação** (Plan mode) → **pausa** para confirmação → executa. |
 | **`agent-work-issue`** | Pool / autonomia: Issue já claimada → plano de implementação → executa sem pausa → `/simplify` → `capture-review-debts` → PR Ready + auto-merge. |
 
-Aqui **não** se implementa código, **não** se escreve plano de implementação, **não** se roda Impeccable craft/critique/polish.
+Aqui **não** se implementa código de produto, **não** se escreve plano de implementação, **não** se roda Impeccable craft/critique/polish. O canvas de rascunho UI/UX é artefato do **gate de intenção**, não entrega de app.
 
 **Shaping (não tour):** aplique [shaping.md](shaping.md) em silêncio — appetite, fatia mínima útil, rabbit holes de produto, self-score ≥4 antes de gravar.
 
@@ -54,7 +58,7 @@ Aqui **não** se implementa código, **não** se escreve plano de implementaçã
 - [ ] 2. Reserva de IDs de uma vez por trilha (roadmap legacy + issuesById())
 - [ ] 3. Por item (ordem topológica): classificar → fatiar → explorar só o suficiente → intenção completa
 - [ ] 4. Sugestão de modelo × effort via model-selection (uma linha por item)
-- [ ] 5. GATE: overview do lote + esboços de fluxo (B/C/D) → confirmar/iterar (PARAR aqui até o humano confirmar)
+- [ ] 5. GATE: overview do lote + canvas UI/UX (se muda UI) + esboços de fluxo → confirmar/iterar (PARAR aqui até o humano confirmar)
 - [ ] 6. Registro: register --blocked (se --plan) → PR Related → merge → promote ready
 ```
 
@@ -88,10 +92,10 @@ Ordem topológica (dependente cita ID do dependido). Por item:
 | Decisão de NÃO fazer | Comentário/doc, não Issue |
 
 2. **Explorar o código o mínimo** — só para apontar **direção** (rotas/pastas/domínios prováveis) e evitar duplicar algo já entregue. Não inventar signatures, collections novas como decisão travada, nem diagramas de componentes.
-3. **Superfície UI (A–D)** como dica para quem for executar — não semear brief Impeccable completo nem wireframe de implementação. Classe C/D: esboço de fluxo persona (ASCII curto) no gate, não especificação de layout.
+3. **Superfície UI (A–D)** como dica para quem for executar — não semear brief Impeccable completo. Classe **B/C/D** (ou qualquer mudança de UI): criar **Cursor canvas** de rascunho UI/UX ([ui-draft-canvas.md](ui-draft-canvas.md) + skill `canvas`) **antes do gate**; ASCII no plano fica opcional. Classe **A** / sem UI: sem canvas.
 4. **Dados (intenção)** ou `Dados: N/A`.
 5. **Posicionamento:** `P0..P3`, `depends`, appetite, janela eleitoral se relevante, `serializes` se tocar recurso compartilhado (ex. migrations) — sem detalhar a migration.
-6. **Plano de intenção** em `docs/plans/<slug>.md` via [intention-template.md](intention-template.md). Self-score ≥4/5 ([shaping.md](shaping.md)).
+6. **Plano de intenção** em `docs/plans/<slug>.md` via [intention-template.md](intention-template.md), com campo **Canvas UI** preenchido (path do `.canvas.tsx` ou `N/A`). Self-score ≥4/5 ([shaping.md](shaping.md)).
 
 ### O que é proibido no plano de intenção
 
@@ -109,6 +113,7 @@ Ordem topológica (dependente cita ID do dependido). Por item:
 - Appetite e fora de escopo (produto)
 - **Direção provável no codebase** (pastas/rotas/domínios — hipotética, revisável)
 - Questões em aberto com **Opções + Recomendação de produto** (não de engenharia)
+- **Se muda UI:** canvas de rascunho UI/UX no gate ([ui-draft-canvas.md](ui-draft-canvas.md)) + link no plano
 
 ## Passo 4 — Modelo × effort
 
@@ -123,10 +128,11 @@ Skill `model-selection`. Registre no cabeçalho (`Model:`) e no gate.
 Antes de criar Issues **ou** abrir PR de planos:
 
 - Overview: ID, título, prio, depends, appetite, modelo, link do plano local
-- Esboços de fluxo persona para superfícies B/C/D (se houver)
+- **Para cada item que muda UI:** link markdown absoluto do canvas `plan-<id>-ui-draft.canvas.tsx` (abrir ao lado do chat) — este é o rascunho visual a validar
+- Esboço textual de fluxo só se ajudar; não substitui o canvas quando há UI
 - Perguntas acumuladas numa rodada, recomendação de produto primeiro
 
-**Pare e espere.** Itere até confirmação explícita do lote. Só então Passo 6.
+**Pare e espere.** Itere (incluindo o canvas, se houver UI) até confirmação explícita do lote. Só então Passo 6.
 
 ## Passo 6 — Registro (ordem fixa)
 

.cursor/skills/plan-issue/intention-template.md

@@ -13,6 +13,7 @@ Issue: #<N> (após `pnpm agent:register`; senão "—")
 Priority: <P0 | P1 | P2 | P3>
 Model: <slug model-selection>
 Impeccable: <A | B | C | D> — <N/A sem UI | encaixe em tela X | fluxo novo em Y>
+Canvas UI: <N/A — sem UI | path absoluto do plan-<id>-ui-draft.canvas.tsx>
 Appetite: <ex.: ~0,5–1 dia eng; um outcome verificável>
 Responsável: —
 
@@ -29,7 +30,8 @@ Responsável: —
 
 ### Esboço de fluxo (B/C/D)
 
-<!-- ASCII de jornada, não layout de implementação. Omitir se A ou só controle isolado. -->
+<!-- Opcional se houver Canvas UI. ASCII de jornada (backup textual), não layout de implementação.
+     Omitir se A / sem UI. O artefato obrigatório do gate para UI é o Cursor canvas — ver ui-draft-canvas.md. -->
 
 \```text
 [início] → … → [outcome]
@@ -77,6 +79,7 @@ Responsável: —
 ## Referências
 
 - GitHub Issue #<N>
+- Canvas UI (gate): <link/path do `.canvas.tsx` ou N/A>
 - <arquivos/rotas úteis para o executor abrir primeiro — como pista, não contrato>
 - `AGENTS.md` / `docs/ARCHITECTURE.md` — só se o item toca convenção já travada no repo
 ````
@@ -84,6 +87,7 @@ Responsável: —
 Notas:
 
 - Alvo: ~60–100 linhas. Mais que isso costuma significar engenharia vazando para a intenção.
-- Classe **A:** `Impeccable: A — N/A`; omita esboço de fluxo.
+- Classe **A:** `Impeccable: A — N/A`; `Canvas UI: N/A`; omita esboço de fluxo.
+- Classe **B/C/D:** canvas obrigatório no gate ([ui-draft-canvas.md](ui-draft-canvas.md)); leia a skill `canvas` ao escrever o `.canvas.tsx`.
 - Não rode `/impeccable` aqui.
 - Self-score shaping ≥4/5 antes de gravar.

.cursor/skills/plan-issue/shaping.md

@@ -53,4 +53,6 @@ Armadilhas se alguém “só completar” o desejo humano:
 4. Direção no codebase é hipótese (não contrato técnico)?
 5. Zero decisões duras de engenharia no plano?
 
+Se o item muda UI: canvas de rascunho no gate ([ui-draft-canvas.md](ui-draft-canvas.md)) antes de registrar — não conta como “engenharia no plano”; é validação visual da intenção.
+
 <4 → corrigir antes de gravar / registrar Issue.

.cursor/skills/plan-issue/skills-map.md

@@ -39,6 +39,8 @@ No Teqo: **idea-refine / interview** antes se vago; **spec + plan + tasks** = es
 
 `frontend-ui-engineering`, `security-and-hardening`, `performance-optimization`, `code-review-and-quality`, `code-simplification`, `observability-and-instrumentation`, `shipping-and-launch`, `ci-cd-and-automation`, `git-workflow-and-versioning`, `deprecation-and-migration`, `debugging-and-error-recovery`, `browser-testing-with-devtools` — entram em `work-issue` / gates do repo, não no registro da Issue.
 
+**Exceção de superfície:** a skill Cursor **`canvas`** é usada no `plan-issue` só para o **rascunho UI/UX do gate** quando o item muda UI ([ui-draft-canvas.md](ui-draft-canvas.md)). Não é implementação de `/campanha` nem substituto de Impeccable.
+
 ## Precedência quando conflita
 
 1. Convenções Teqo (`AGENTS.md`, access, migrations, Consent fail-closed)  

.cursor/skills/plan-issue/ui-draft-canvas.md

@@ -0,0 +1,54 @@
+# Canvas de rascunho UI/UX (plan-issue)
+
+Quando o item **muda UI** (classe Impeccable **B / C / D**, ou qualquer superfície que o usuário vê/toca), o gate **obrigatoriamente** apresenta um **Cursor canvas** com rascunho visual da intenção — não ASCII sozinho, não wireframe de implementação.
+
+Leia e siga a skill `canvas` (`~/.cursor/skills-cursor/canvas/SKILL.md`) ao criar/editar o arquivo.
+
+## Quando criar
+
+| Situação | Canvas? |
+| -------- | ------- |
+| `Impeccable: A` / N/A sem UI / chore sem superfície | Não |
+| Encaixe em tela existente (B) | Sim — estado atual → estado desejado da área tocada |
+| Fluxo novo ou redesign local (C/D) | Sim — jornada + telas/estados chave |
+| Só copy/label sem rearranjo | Não (a menos que o humano peça ver o contexto) |
+
+Um canvas por item com UI (ou um canvas do lote com secções por ID, se o lote for pequeno e as superfícies forem do mesmo fluxo). Preferir **um arquivo por item** (`plan-<id>-ui-draft.canvas.tsx`).
+
+## Onde gravar
+
+Path canônico do IDE (não no repo Teqo):
+
+`/Users/<user>/.cursor/projects/<workspace>/canvases/plan-<id>-ui-draft.canvas.tsx`
+
+Ex.: `plan-c42-ui-draft.canvas.tsx`. Escreva o arquivo com a tool de write; não peça `mkdir`. No chat do gate, linke o path absoluto em markdown.
+
+## O que mostrar (produto)
+
+Rascunho de **intenção de uso**, legível sozinho:
+
+1. **Persona + job** (uma linha).
+2. **Jornada** (passos / estados) — o que a pessoa vê e decide.
+3. **Layout esquemático** das superfícies tocadas: zonas (lista, detalhe, formulário, mapa, empty, erro), hierarquia de atenção, CTAs primários/secundários.
+4. **Estados críticos** se mudarem o aceite (vazio, loading, sem permissão, fail-closed) — só os que importam ao produto.
+5. **Fora de escopo visual** em callout curto (o que este item *não* redesenha).
+
+Use `Stack` / `Grid` / `Row` / `Card` / `Pill` / `Callout` / `Text` / `H1`–`H3` de `cursor/canvas`. Cores só via `useHostTheme()`. Pode usar caixas/`div` com bordas de token para simular regiões de tela — isso é rascunho de UX, não componente do app.
+
+## O que é proibido no canvas
+
+- Assinaturas, nomes de arquivos/componentes obrigatórios, schema, migrations
+- Brief Impeccable completo, craft/critique/polish, paleta/brand do produto Teqo
+- Mock com dados inventados como se fossem métricas reais (“No data”, KPIs zerados) — omita secções sem conteúdo
+- Gradientes, emojis, box-shadow, arco-íris (regras da skill canvas)
+- Travar o executor numa única forma técnica
+
+## Relação com o plano em `docs/plans/`
+
+- No plano: campo **Canvas UI:** link/path do `.canvas.tsx` (ou `N/A — sem UI`).
+- Esboço ASCII no markdown vira **opcional** (backup textual); o **canvas é o artefato do gate** para UI.
+- O canvas **não** é commitado no repo Teqo por default — é artefato de sessão do gate. Se o humano pedir arquivar no repo, só com pedido explícito (fora do fluxo padrão).
+
+## Gate
+
+Antes de `pnpm agent:register`, mostre o overview do lote **e** o(s) canvas de UI. Itere no canvas até o humano confirmar a intenção visual. Só então registre a Issue.