@mir-code/specs-platform 1.0.1

package/assets/template/.agents/skills/refinement-runner/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: refinement-runner
+description: Refinamento com execução imediata — entende a atividade, mapeia o terreno, esgota todas as dúvidas antes de tocar em código, implementa e PARA antes de commitar para code review humano, sem criar nem alterar documento em `.specs/specs/`. Carregue ao pedir "refinar e executar", "fazer direto", ou ao descrever uma atividade para ver implementada sem passar por spec.
+---
+
+# refinement-runner
+
+Existe para o caso em que **documentar a task custa mais do que fazê-la**: você faz o trabalho de
+refinamento — entender, mapear o terreno, fechar o escopo, **tirar todas as dúvidas** — e em
+seguida executa, sem produzir nenhum documento em `.specs/specs/`.
+
+É a fusão do `refinement` (entender + mapear + fechar requisitos) com o `feature-runner`
+(implementar + verificar + halt). Quando a atividade for grande o bastante para merecer spec
+versionada, **pare e recomende** o `refinement`.
+
+Equivalências de tools Claude Code ↔ Cursor: `.agents/RUNTIME.md`.
+
+## Ponto de partida obrigatório
+
+**Carregue a skill `execution-protocol` antes de qualquer coisa** — princípios invioláveis,
+verificação do repositório, convenções de código, ciclo halt → ajustar → complete.
+
+Além dela: **nunca crie nem edite arquivos em `.specs/specs/`.** Nem task, nem `overview.md`, nem
+`meta.json`. Seu entregável é código no working tree. Precisa de documentação? é sinal de que a
+atividade deveria ter ido para o `refinement` — diga isso.
+
+## Skills por camada
+
+| Carregue | Quando |
+|---|---|
+| `execution-protocol` | **sempre**, antes de tudo |
+| `requirements-closure` | **sempre** — é ela que define quando o escopo está fechado, e aqui não há spec para conferir depois |
+| `test-strategy` | a atividade produz código testável |
+| `verification` | a atividade produz código com teste automatizado |
+| `input-security` | a atividade toca input do usuário (opcional — só se o projeto adotar essa skill) |
+| `ui-standards` | a atividade cria ou altera tela/componente (opcional — só se o projeto adotar essa skill) |
+| `prototype-check` | a atividade tem entregável visual |
+
+`spec-writing` **não** é carregada: você não escreve spec. O que a substitui é a skill
+`requirements-closure` como régua do escopo consolidado da Fase 3.
+
+## Fluxo
+
+Ponto de entrada pelo contexto: pedido novo ⇒ **0**; "Ajustar: ..." e "Complete" ⇒ ciclos do
+`execution-protocol`. Aqui a entrega é única, então não há halt intermediário nem "Prosseguir":
+o halt da Fase 7 já é o final, e é ele que oferece "Complete".
+
+### 0. Protótipo (quando a atividade for visual)
+
+Antes de ler código, **descubra qual ferramenta de protótipo o projeto usa** — o bloco `prototype`
+do `.specs/config.json`, sobrescrito pelo `meta.json` da feature quando ele declarar o seu:
+
+- `tool: "claude-design"` ⇒ canvas do Claude Design, endereçado pela `url`; as decisões versionadas
+  estão em `<designDir>/README.md`. Não há node ID nem MCP — referencie artboards pelo nome.
+- `tool: "pencil"` ⇒ arquivo `.pen` (encriptado, nunca `Read`/`Grep`); a consulta é pelo Pencil MCP,
+  e é ali que você **obtém os node IDs** dos nós alvo.
+- sem bloco ⇒ o projeto não tem protótipo: siga sem fase visual e registre isso no relatório.
+
+Carregue `prototype-check` para o fluxo de consulta. Sem acesso ao protótipo para uma tela que
+deveria existir, **pare e informe o usuário**.
+
+### 1. Entender a atividade
+
+Identifique **o quê**, **por quê** e **onde** (frontend, backend, ambos, infra, docs).
+
+**Teste de tamanho — faça já.** Se a atividade toca mais de uma camada com contratos novos entre
+elas, ou se você já enxerga que ela se quebraria em três ou mais tasks independentes, **pare** e
+recomende o `refinement` (com o `feature-runner` depois). Explique o porquê em uma linha e deixe a
+decisão com o usuário via `AskUserQuestion` / `AskQuestion`: "Refinar e documentar primeiro" vs.
+"Seguir direto mesmo assim".
+
+### 2. Mapear o terreno
+
+Siga [mapear-terreno.md](../refinement/references/mapear-terreno.md) — inclusive a leitura
+**obrigatória** de `.specs/STATE.md` `## Decisions` antes de qualquer decisão arquitetural.
+
+Duas paradas específicas desta skill:
+
+- **Reuso antes de criação.** Procure utilitários, tipos compartilhados, componentes e hooks que já
+  existem antes de planejar código novo.
+- **Task já documentada.** Encontrou em `.specs/specs/` uma task que cobre o que foi pedido?
+  **pare e avise**: o caminho certo ali é o `feature-runner`, não você.
+
+### 3. Esgotar as dúvidas — o portão
+
+Esta é a fase que justifica sua existência. **Você não passa daqui com pergunta em aberto.** Sem
+spec escrita, não há segunda chance de pegar a ambiguidade: ela vira código errado direto.
+
+1. **Rode o sweep das 9 dimensões implícitas** da skill `requirements-closure`. Cada dimensão
+   resolve para um requisito **ou** um `N/A porque <motivo>`. Nunca em branco. É o que impede a
+   pergunta que ninguém lembrou de fazer — falha de dependência externa, idempotência, ciclo de
+   vida do dado.
+2. **Classifique cada decisão** que a implementação vai exigir:
+   - **Decidível pelo código** — o projeto já tem convenção, padrão análogo ou tipo pronto. Decida
+     sozinho e registre como decisão no relatório. Não pergunte o óbvio.
+   - **Ambígua de verdade** — escopo, comportamento esperado, contrato de API, biblioteca, UX,
+     tratamento de erro, regra de negócio, caminho triste. **Pergunte.**
+3. **Dispare as perguntas agrupadas** (`AskUserQuestion` / `AskQuestion`, até 4 por chamada), cada
+   uma com 2–4 opções concretas e uma recomendação quando você tiver opinião informada.
+
+Nunca pergunte "posso prosseguir?". Só saia daqui quando a próxima pergunta que você consegue
+formular for sobre algo fora do escopo.
+
+### 4. Fechar o escopo
+
+Consolide **para si mesmo** (ainda sem escrever arquivo nenhum), aplicando o portão de fechamento
+da skill `requirements-closure`:
+
+- o que entra e o que **não** entra;
+- os critérios de aceite em EARS, objetivos e ancorados em código que existe de verdade;
+- a tabela de premissas — o que você decidiu sozinho, com default e racional;
+- os arquivos que você espera tocar;
+- o gate que vai fechar a entrega (skill `test-strategy`);
+- a checklist de code review que vai para o relatório de halt.
+
+**Esse consolidado é o que substitui o documento de spec** e é o que você reporta no halt.
+
+### 5. Verificar o repositório
+
+Skill `execution-protocol`.
+
+### 6. Implementar
+
+Siga [implementar.md](../feature-runner/references/implementar.md), pulando o passo de marcar
+`in-progress` (não há arquivo de task). Os critérios de aceite são os da Fase 4.
+
+Descobriu na implementação que uma decisão da Fase 3 não se sustenta? **volte e pergunte** — não
+improvise uma saída.
+
+### 7. Verificação e halt
+
+Skill `verification`, depois
+[relatorio-halt.md](../execution-protocol/references/relatorio-halt.md). Deixe explícito no
+relatório que **nenhum arquivo em `.specs/specs/` foi criado ou alterado**, e inclua o escopo
+consolidado da Fase 4 junto com a tabela de premissas.
+
+### 8. Ajustar / Complete
+
+Ciclos do `execution-protocol`. Sem arquivo de task, o commit não carrega `Refs:` nem atualização
+de status — a mensagem descreve o que foi feito.
+
+## Specs Platform
+
+O botão "+" da sidebar pergunta entre **Refinamento** (`refinement`) e **Refinamento + execução**
+(você). A UI envia `POST /api/jobs` com `kind: refinement-runner` e a CLI escolhida.

package/assets/template/.agents/skills/requirements-closure/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: requirements-closure
+description: Como fechar requisitos sem deixar ambiguidade em silêncio — notação EARS para critérios de aceite, IDs de requisito rastreáveis, o sweep das 9 dimensões implícitas (validação, falha parcial, idempotência, auth/rate-limit, concorrência, ciclo de vida do dado, observabilidade, falha de dependência externa, transição de estado), o portão de fechamento e a tabela de premissas. Carregue antes de redigir critérios de aceite em qualquer refinamento, com ou sem spec escrita.
+---
+
+# Fechamento de requisitos
+
+Esta skill responde a uma pergunta só: **este requisito pode ser lido de duas formas?** Enquanto
+puder, ele não está pronto — nem para virar spec, nem para virar código.
+
+Vale para quem escreve spec (`refinement`) e para quem fecha escopo de cabeça (`refinement-runner`).
+O `spec-writing` diz *onde* o critério mora no arquivo; esta skill diz *como ele é escrito e quando
+está completo*.
+
+## Fatos você descobre, decisões você pergunta
+
+Antes de perguntar qualquer coisa ao usuário, resolva sozinho tudo que é descobrível lendo o
+ambiente. Pergunta que o código já responde queima a atenção dele e um turno.
+
+**Cadeia de verificação de conhecimento** — em ordem estrita, nunca pule para o passo 5:
+
+```
+1. Código      → o que já existe, convenções e padrões em uso no monorepo
+2. Docs        → CLAUDE.md (raiz e apps), .specs/specs/, .specs/discoveries/, .specs/STATE.md
+3. Context7    → doc atual da lib (subagente com MCP context7) quando a decisão depende de versão
+4. Busca web   → doc oficial, fonte reputada
+5. Declarar incerteza → "não tenho certeza sobre X — meu raciocínio é Y, confirme"
+```
+
+**Nunca invente.** API, comportamento de lib, nome de campo, formato de payload: não achou? diga
+"não sei" ou "não encontrei documentação". Requisito fabricado se propaga para o critério de
+aceite, para o teste e para o código — e o teste passa provando a coisa errada.
+
+Reserve as perguntas para o que é genuinamente decisão do usuário: escopo, prioridade,
+comportamento de produto, trade-off, o que fazer no caminho triste.
+
+## O que é critério de aceite, e o que não é
+
+Antes de escrever, decida **se aquilo é critério**. EARS não protege contra isso: dá para escrever
+"QUANDO o body é validado ENTÃO o schema DEVE usar `.strict()`" — está em EARS e continua sendo
+decisão de estrutura interna, não entrega.
+
+**Critério de aceite é comportamento observável na fronteira da entrega:** resposta de API, o que
+aparece na tela, o que fica persistido, invariante que precisa valer. Ele descreve **o que a
+entrega faz**, não como ela é por dentro.
+
+### O teste do refactor
+
+> **Se eu refatorar sem mudar comportamento, esse item quebra?**
+> Sim ⇒ **não é critério de aceite.** É nota de implementação ou item de code review.
+
+Um segundo teste, equivalente: *um teste que desconhece a implementação consegue provar isso?* Se
+a única forma de "verificar" é abrir o arquivo e olhar, é inspeção — e inspeção mora na
+`## Code Review Checklist`.
+
+| Não é critério (vai para a Code Review Checklist) | É critério (fica no bloco `<details>`) |
+|---|---|
+| `CreateQueryRequestDTO` ganha `objective?: QueryObjective` | QUANDO `POST /queries` recebe body sem `objective` ENTÃO o sistema DEVE persistir `BUY` |
+| O schema do controller segue `.strict()` | SE o body traz campo desconhecido ENTÃO o sistema DEVE responder 400 sem processar a requisição |
+| A entidade não expõe setter para o campo | QUANDO uma query `COMPLETED` é reprocessada ENTÃO o sistema DEVE manter o `objective` original |
+| Teste mora em `__tests__/unit/useCases/...` | O sistema DEVE cobrar o mesmo preço para a mesma placa e SKU, qualquer que seja o `objective` |
+| Nenhum índice novo na tabela | O sistema DEVE manter o parâmetro fora da chave de cache e de dedupe |
+
+Repare no padrão: a coluna da direita sobrevive a renomear DTO, mover arquivo e trocar ORM. A da
+esquerda não.
+
+### A exceção: quando a estrutura é a entrega
+
+A regra não é "nunca cite arquivo". É *a estrutura é o produto, ou o caminho até ele?*
+
+Numa task cuja entrega **é** a migration, `coluna objective com default BUY, sem backfill` é o
+desfecho — é o que o usuário da task está pedindo, e um teste de schema prova. Numa task de caso de
+uso, a mesma frase é detalhe de como você escolheu persistir.
+
+Na dúvida, pergunte: **se isso mudar, o consumidor da entrega percebe?** Sim ⇒ critério.
+
+### Por que isso importa aqui
+
+1. **O Verifier exige evidência.** A skill `verification` cobra `file:line` + a expressão da
+   asserção para cada critério. Nota de implementação não tem asserção que prove valor — ela
+   entope a tabela de cobertura com linhas que nunca fecham.
+2. **Critério estrutural envelhece rápido.** Ele quebra no primeiro refactor e a spec passa a
+   mentir, o que é pior do que não ter dito nada.
+3. **Hoje isso está escrito duas vezes.** Nas specs atuais, os itens de padrão aparecem no bloco
+   `<details>` **e** repetidos, condensados, na `## Code Review Checklist`. Escrevendo cada coisa
+   no lugar dela, a duplicação some.
+
+## Critérios de aceite em EARS
+
+Todo critério de aceite resolve para **exatamente um** destes padrões. O verbo **DEVE** é
+obrigatório em todos — é ele que marca a linha como requisito verificável.
+
+| Padrão | Palavra-chave | Forma | Para |
+|---|---|---|---|
+| Ubíquo | (nenhuma) | O sistema DEVE `<resposta>` | Invariante sempre válida |
+| Dirigido a evento | QUANDO | QUANDO `<gatilho>` ENTÃO o sistema DEVE `<resposta>` | Reação a um evento discreto |
+| Dirigido a estado | ENQUANTO | ENQUANTO `<estado>` o sistema DEVE `<resposta>` | Comportamento durante um estado |
+| Opcional | ONDE | ONDE `<capacidade presente>` o sistema DEVE `<resposta>` | Atrás de flag ou capacidade opcional |
+| Indesejado | SE / ENTÃO | SE `<condição indesejada>` ENTÃO o sistema DEVE `<resposta>` | Erro, falha, input inválido, timeout |
+| Composto | combinação | ENQUANTO `<estado>`, QUANDO `<gatilho>` o sistema DEVE `<resposta>` | Comportamento mais rico |
+
+**Por que seis padrões e não um.** Com só `QUANDO/ENTÃO`, falha e transição de estado viram nota
+de rodapé em prosa. Com `SE/ENTÃO` e `ENQUANTO` de primeira classe, elas viram critério — e
+critério vira teste.
+
+Regras:
+
+- **Um comportamento por critério.** Nunca junte dois com "e também".
+- **Valor concreto, nunca advérbio.** `DEVE responder 409 com `errorCode: EMAIL_ALREADY_REGISTERED``,
+  não "DEVE tratar graciosamente". "Rápido", "amigável" e "corretamente" não são verificáveis.
+- **Desfecho preciso.** O critério define o valor esperado: status, campo, mensagem, estado
+  persistido. Sem desfecho preciso o teste vira asserção vaga que passa com implementação errada.
+- **Ancorado em código real.** Cite rota, componente, tipo e tabela que existem — salvo quando a
+  task é justamente criá-los, e aí seja explícito ("Criar `POST /api/v1/vehicles`").
+- **Sem token visual fixo** (hex, px, peso de fonte): vive no protótipo, não na spec.
+
+Exemplos:
+
+```markdown
+- [ ] QUANDO o usuário submete CPF já cadastrado ENTÃO o sistema DEVE responder 409 com
+      `errorCode: CPF_ALREADY_REGISTERED` e não criar registro em `users`
+- [ ] SE o provedor veicular exceder 5s ENTÃO o sistema DEVE abortar a chamada, registrar
+      `provider_timeout` no log e responder 504 com mensagem genérica
+- [ ] ENQUANTO a consulta estiver em `processing` o sistema DEVE exibir o skeleton do relatório
+      em vez do conteúdo parcial
+- [ ] O sistema DEVE persistir o identificador sensível como hash truncado, nunca em claro
+```
+
+## IDs de requisito
+
+Todo critério de aceite de task **Large** (5+ critérios ou 2+ camadas) carrega um ID rastreável.
+
+- Formato: `<CATEGORIA>-<NN>` em maiúsculas — `CADASTRO-01`, `CONSULTA-07`, `CMS-03`.
+- A categoria é derivada do slug da feature, não da task.
+- Numeração sequencial por feature, **permanente**: não reaproveite número de requisito removido.
+- No arquivo da task o ID prefixa o critério: `- [ ] **CADASTRO-03** — QUANDO ... ENTÃO ...`.
+
+O ID é o que permite ao `verification` dizer "CADASTRO-03 coberto em
+`tests/unit/auth-use-cases.test.ts:88`" em vez de "os testes parecem cobrir o cadastro".
+
+Task pequena e coesa (≤4 critérios, uma camada) pode dispensar IDs. Declare isso no relatório.
+
+## Sweep das 9 dimensões implícitas
+
+O que mais falta em spec não é o que foi escrito errado — é o que ninguém lembrou de perguntar.
+Antes de fechar o escopo, passe por **cada** dimensão abaixo. Cada uma resolve para um requisito
+**ou** para um `N/A porque <motivo>` explícito. **Campo em branco é proibido.**
+
+| Dimensão | O que cobrir |
+|---|---|
+| Validação e limites de input | formato, tamanho máximo, alfabeto permitido, sanitização |
+| Falha e falha parcial | timeout, gravação parcial, rollback, o que o usuário vê quando quebra no meio |
+| Idempotência / retry / duplicata | reenvio seguro, chave de deduplicação, clique duplo no submit |
+| Fronteira de auth e rate limit | quem pode chamar, o que acontece sem token, throttle |
+| Concorrência e ordenação | corrida entre requisições, garantia de ordem, lock |
+| Ciclo de vida do dado | TTL, expiração, arquivamento, deleção, o que acontece com dado órfão |
+| Observabilidade | o que é logado, com que nível, qual métrica, correlação de request |
+| Falha de dependência externa | provedor veicular fora do ar, gateway de pagamento recusando, fallback, circuit breaker |
+| Integridade de transição de estado | transições válidas, guarda contra transição ilegal, estado terminal |
+
+Profundidade pelo tamanho da atividade:
+
+- **Grande / complexa** (2+ camadas, contrato novo, ou 3+ tasks): **todas** as 9 dimensões,
+  cada uma com requisito ou `N/A porque`.
+- **Média** (uma camada, escopo claro): só as dimensões obviamente presentes no domínio da task;
+  colapse o resto em uma linha `demais dimensões N/A para este escopo`.
+- **Pequena** (ajuste pontual, ≤3 arquivos): pule o sweep.
+
+O `N/A porque` é **obrigatório** e não é burocracia: é ele que impede inventar requisito só para
+preencher a tabela. `Concorrência: N/A porque a operação é um GET sem efeito colateral` é uma
+resposta completa.
+
+Bound: o sweep é limitado ao escopo **desta** atividade. Ele esclarece requisito existente, nunca
+inventa capacidade nova — "Fora de escopo" continua sendo o contrapeso.
+
+> Em produto que depende de integração externa, as dimensões que mais mordem são **falha de
+> dependência externa** (provedor
+> veicular, gateway de pagamento), **idempotência** (webhook de pagamento reentregue) e **ciclo de
+> vida do dado** (resultado em cache, identificador sensível, expiração de artefato gerado). Não
+> passe batido nelas.
+
+## Portão de fechamento (antes de apresentar o escopo)
+
+Três checagens. Enquanto qualquer item ficar aberto e não registrado, o escopo **não** vai para
+aprovação nem para implementação.
+
+1. **Ambiguidade e precisão.** Todo critério tem uma leitura só **e** um desfecho preciso. Falhou
+   em qualquer das duas: resolva com o usuário, quebre em dois critérios, ou registre como
+   premissa com o default escolhido e o racional.
+2. **Fechamento de questões em aberto.** Enumere toda decisão que surgiu durante o refinamento.
+   Cada uma foi **resolvida com o usuário** ou virou **premissa registrada**. Nada segue sem marca.
+3. **Gray area recusada vira premissa.** O que o usuário não quis discutir, ou que nem chegou a
+   ser discutido, é escrito na tabela de premissas com o default do agente e o motivo — nunca
+   descartado em silêncio.
+
+Escala pelo tamanho: **grande/complexa** = portão completo; **média** = resolva as ambiguidades
+óbvias e registre o resto como premissa; **pequena** = pule.
+
+## Tabela de premissas e questões em aberto
+
+Vive num bloco `<details>` chamado **Premissas e questões em aberto**, logo antes do bloco de
+Testes (ver `spec-writing`). No `refinement-runner`, que não escreve spec, ela vai no relatório
+de halt.
+
+```markdown
+<details>
+<summary>Premissas e questões em aberto</summary>
+
+| Premissa / decisão | Default escolhido | Racional | Confirmado? |
+|---|---|---|---|
+| Webhook reentregue pelo gateway | dedup por `providerEventId` único | o gateway não garante entrega única | não |
+
+**Questões em aberto:** nenhuma — todas resolvidas ou registradas acima.
+
+</details>
+```
+
+A linha `**Questões em aberto:**` é obrigatória. Se houver questão viva de verdade, liste-a e diga
+a quem ela é endereçada — mas então o escopo não está fechado, e isso precisa aparecer no relatório
+como bloqueio, não como nota de rodapé.
+
+## Verificação determinística
+
+Antes de apresentar a spec, rode:
+
+```bash
+node .agents/scripts/validate-spec.mjs .specs/specs/<slug>/feat-<slug>-<task>.md
+```
+
+Ele checa a metade estrutural deste portão — frontmatter válido, ordem das seções, ausência de H1
+no corpo, linha em branco nos `<details>`, `classDef` do Mermaid, critério sem `DEVE`, premissa com
+célula vazia, formato de ID de requisito. Saída ≠ 0 significa **pare e corrija** antes de
+apresentar.
+
+O script confere estrutura; o julgamento continua seu — se a interpretação está certa e se o
+desfecho é preciso, só você sabe.

package/assets/template/.agents/skills/spec-writing/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: spec-writing
+description: Como escrever e manter as specs de `.specs/specs/` — estrutura fixa da página de tarefa (contexto, visão técnica com diagrama Mermaid e blocos expansíveis, escopo, code review checklist), o `overview.md` de cada feature, o frontmatter, o `meta.json`, o registro de Execuções e as heurísticas de quebra em tasks. Carregue antes de criar, refinar ou atualizar qualquer arquivo em `.specs/specs/`.
+related-skills: requirements-closure, test-strategy
+---
+
+# Escrita de specs
+
+As specs vivem em `.specs/specs/<slug-da-feature>/` e são renderizadas pela Specs Platform
+(`specs start`). A estrutura de diretório, a nomenclatura de arquivos e o `meta.json` estão em
+`.specs/specs/CLAUDE.md` — esta skill cobre **o que escrever dentro dos arquivos**.
+
+## Estrutura fixa da página de tarefa
+
+Toda tarefa segue esta ordem de seções, sem exceção:
+
+```
+## Contexto da alteração          (termina com a lista "**Depende de:**")
+## Visão Técnica
+   diagrama Mermaid + legenda
+   ### O que muda, em resumo      (tabela curta)
+   ### Detalhamento técnico       (blocos <details>)
+## Escopo
+   ### Fora de escopo
+## Code Review Checklist
+```
+
+**Não existem** as seções `Critérios de Aceite`, `Detalhes Técnicos`, `Testes` e `Dependências`
+como seções de primeiro nível. Os critérios e os detalhes vivem dentro dos blocos expansíveis,
+testes são um bloco expansível, e as dependências são a lista `**Depende de:**` no fim do
+Contexto.
+
+**Nunca escreva `# Título` no corpo.** O `title` do frontmatter já vira o `<h1>` da página; um H1
+no corpo duplica o título (o renderer descarta o duplicado, mas o arquivo fica sujo).
+
+### Contexto da alteração
+
+Dois a quatro parágrafos curtos respondendo: como funciona hoje, o que passa a funcionar
+diferente, e o que o usuário percebe (ou explicitamente não percebe). Sem detalhe de
+implementação — isso é o detalhamento técnico.
+
+Termina com:
+
+```markdown
+**Depende de:**
+
+- [Título da task](./feat-<slug>-<task>.md) — o que ela entrega para esta
+```
+
+Quando não há dependência, diga isso explicitamente ("Nenhuma task. É a primeira da feature.").
+
+### Diagrama da Visão Técnica (obrigatório)
+
+Um `flowchart` Mermaid com a visão geral do que será feito. Sempre com estes `classDef`:
+
+```
+  classDef changed fill:#3b2f00,stroke:#eab308,color:#fde68a
+  classDef added fill:#052e1a,stroke:#22c55e,color:#bbf7d0
+  classDef removed fill:#3b0d0d,stroke:#ef4444,color:#fecaca
+  classDef untouched fill:#151515,stroke:#2a2a2a,color:#9ca3af
+```
+
+Regras:
+
+- **Um nó por recurso/componente real tocado** — use case, entidade, tabela, endpoint, job, fila,
+  tela, componente, DAL, integração externa. Nada genérico como "o backend".
+- **Cor pela natureza da mudança:** `:::changed` (amarelo) alterado, `:::added` (verde)
+  adicionado, `:::removed` (vermelho) removido, `:::untouched` (cinza) só o contexto mínimo que
+  faz o fluxo ter sentido.
+- Cole a legenda logo abaixo do bloco:
+  `> 🟡 alterado · 🟢 adicionado · 🔴 removido · ⚪ inalterado (contexto)`
+- Agrupe em `subgraph` por etapa ou camada. Prefira `flowchart TB` com `direction LR` **dentro**
+  de cada subgraph: faixas horizontais empilhadas rendem um diagrama equilibrado, enquanto `LR`
+  puro produz diagramas larguíssimos e ilegíveis.
+- Ligue arestas a **nós específicos**, nunca ao subgraph inteiro — aresta apontando para um
+  subgraph faz o Mermaid ignorar o `direction` interno dele.
+- Máximo ~15 nós. O que não couber vira texto no detalhamento.
+- Sem aspas duplas dentro do rótulo; `<br/>` para quebrar linha.
+- Um card `:::removed` pode marcar **acoplamento proibido** em vez de código deletado (ex.: "o que
+  não pode passar a depender deste campo") — quando fizer isso, explique na linha da legenda.
+
+### Blocos expansíveis do detalhamento técnico
+
+A linha em branco depois do `</summary>` e antes do `</details>` é obrigatória — sem ela o
+markdown interno não é interpretado:
+
+```markdown
+<details>
+<summary>Título do recorte</summary>
+
+Explicação curta do recorte.
+
+- [ ] critério de aceite verificável
+
+</details>
+```
+
+Regras:
+
+- Um bloco por **recorte coeso**: etapa do fluxo, endpoint, seção de tela, política de erro.
+- **Os critérios de aceite moram dentro do bloco do recorte a que pertencem**, logo abaixo da
+  explicação.
+- Blocos temáticos obrigatórios quando se aplicarem: `Segurança e sanitização de inputs`,
+  `Premissas e questões em aberto`, `Testes` e, em frontend, `Responsividade`,
+  `Estados de UI — loading, erro, vazio`, `Acessibilidade e animações`.
+- **`Premissas e questões em aberto` é obrigatório em toda task média ou grande** — é onde a
+  ambiguidade que não foi resolvida com o usuário fica registrada com default e racional, em vez
+  de sumir. Formato e regra na skill `requirements-closure`.
+- **`Testes` declara `**Tipo:**` e `**Gate:**`** com o comando real do pacote tocado. Formato e
+  matriz de cobertura na skill `test-strategy`.
+- **Nada de headings markdown (`###`) dentro de `<details>`** — eles aparecem no índice lateral
+  apontando para conteúdo fechado. Use **negrito** para subtítulos internos.
+- O conteúdo fora dos blocos precisa ser lido de ponta a ponta em menos de um minuto: contexto,
+  diagrama, tabela-resumo, escopo e checklist. Todo o resto fica colapsado.
+
+### Tabela "O que muda, em resumo"
+
+Três colunas — `#`, `Mudança`, `Efeito`. Uma linha por mudança relevante, tipicamente 4 a 8.
+O efeito é a consequência prática ("o worker deixa de ficar bloqueado"), não a repetição da
+mudança.
+
+## A `## Code Review Checklist`
+
+É **a casa dos itens de estrutura interna** — não um resumo dos critérios de aceite.
+
+A divisão, cuja regra completa está na skill `requirements-closure`:
+
+- **Bloco `<details>`** → comportamento observável na fronteira. Vira teste, e o Verifier cobra
+  `file:line` + asserção para cada um.
+- **Code Review Checklist** → o que só se verifica abrindo o arquivo: path e nomenclatura, nome de
+  DTO/tipo, padrão aplicado (`.strict()`, `private readonly`, allowlist de enum), ausência
+  deliberada (sem índice novo, sem setter, sem backfill), acoplamento que não pode nascer.
+
+O teste para saber onde cada item mora: **se eu refatorar sem mudar comportamento, isso quebra?**
+Sim ⇒ Code Review Checklist.
+
+**Não repita.** Se um item já é critério de aceite num bloco, ele não volta aqui condensado — é
+duplicação que envelhece em dois lugares ao mesmo tempo. A checklist cobre o que os critérios
+deliberadamente **não** cobrem.
+
+Escreva cada item como algo que o revisor consegue marcar olhando o diff, e específico:
+`Enum validado por allowlist no schema .strict() do controller`, não `Validação OK`.
+
+## O `overview.md` da feature
+
+Toda feature tem `.specs/specs/<slug>/overview.md` — a página exibida ao clicar na feature na
+sidebar. Sem ele, a plataforma redireciona para a primeira task.
+
+```
+---
+title: "<Título da feature, igual ao meta.json>"
+description: "<mesma descrição do meta.json>"
+---
+
+## O que será feito          (problema, decisão e desenho geral — 3 a 5 parágrafos curtos)
+## Visão Técnica
+   diagrama Mermaid MACRO + legenda
+   ### Frentes de trabalho             (tabela: frente · o que entrega · nº de tasks)
+   ### Ordem de execução               (cadeia crítica e o que roda em paralelo)
+```
+
+- Sem `status` no frontmatter e **fora** de `pages` no `meta.json` — não é uma task.
+- A lista de tasks com status é renderizada automaticamente abaixo do conteúdo. **Não escreva
+  essa lista à mão.**
+- O diagrama do overview é **macro** (granularidade de frente/entrega); o de cada task é **micro**
+  (granularidade de arquivo/componente). Mesmas cores nos dois.
+- Obrigatório ao criar feature nova. Ao adicionar uma task a uma feature existente, atualize o
+  overview se a task mudar o desenho macro.
+
+## Frontmatter da tarefa
+
+```yaml
+---
+title: "<Camada/Descrição da tarefa>"
+description: "<Frase curta descrevendo o escopo>"
+status: pending        # pending | in-progress | completed | blocked
+---
+```
+
+**O `title` descreve só a tarefa, sem repetir o nome da feature.** A plataforma já exibe a feature
+como sobretítulo acima do H1 e agrupa as tarefas por feature na sidebar — repetir o prefixo
+("Login — Frontend" dentro da feature "Login") gasta a linha inteira com informação redundante.
+Escreva `"Frontend (tela de login)"`, não `"Login — Frontend (tela de login)"`. Em specs antigas
+que ainda carregam o prefixo, o renderer o remove na exibição.
+
+O `status` é responsabilidade de quem executa (`feature-runner`), não de quem refina.
+
+## Critérios de aceite — como redigir
+
+**A notação é EARS e a fonte de verdade é a skill `requirements-closure`** — carregue-a antes de
+redigir. Em resumo: todo critério resolve para um dos seis padrões (ubíquo, `QUANDO`, `ENQUANTO`,
+`ONDE`, `SE`, composto) e carrega o verbo **DEVE**.
+
+```markdown
+- [ ] **CADASTRO-03** — QUANDO o usuário submete CPF já cadastrado ENTÃO o sistema DEVE responder
+      409 com `errorCode: CPF_ALREADY_REGISTERED` e não criar registro em `users`
+```
+
+O prefixo `**CATEGORIA-NN**` é o **ID de requisito**, obrigatório em task com 5+ critérios ou 2+
+camadas — é ele que permite ao Verifier dizer "CADASTRO-03 coberto em `auth-use-cases.test.ts:88`".
+
+E ainda:
+
+- **Objetivos:** não "funcionar bem", mas "retorna 200 com payload `{ id, name }` para input
+  válido".
+- **Testáveis:** um humano ou um E2E verifica sem ambiguidade.
+- **Ancorados no código real:** cite rotas, componentes, arquivos e tipos que existem. Não invente
+  — a menos que a task seja justamente criá-los, e aí seja explícito ("Criar endpoint `POST
+  /api/v1/vehicles`").
+- **Sem tokens visuais fixos** (cores hex, px, pesos de fonte): eles mudam no protótipo e a doc
+  fica mentindo. Descreva estrutura e intenção; quem implementa extrai os valores do protótipo.
+
+## Validação determinística antes de apresentar
+
+Depois de escrever ou editar qualquer arquivo de task, rode:
+
+```bash
+node .agents/scripts/validate-spec.mjs .specs/specs/<slug>/feat-<slug>-<task>.md
+```
+
+Ele checa por código o que esta skill exige de memória: frontmatter, ordem das seções, ausência de
+H1 no corpo, `**Depende de:**`, `### Fora de escopo`, os quatro `classDef` do Mermaid, linha em
+branco nos `<details>`, heading proibido dentro de `<details>`, critério fora de EARS, ID de
+requisito malformado, premissa com célula vazia e presença do arquivo em `pages` do `meta.json`.
+
+**Saída ≠ 0 = pare e corrija** antes de apresentar a spec. Rode no arquivo que você tocou — `--all`
+existe para inventário e hoje acusa as 225 specs no formato antigo, que não são escopo desta rodada.
+
+## Registro de Execuções
+
+Quem executa acrescenta, ao fim do arquivo, depois de um `---`. **Cada execução é um bloco
+expansível** — o histórico cresce sem empurrar o conteúdo da spec para longe:
+
+```markdown
+## Execuções
+
+<details>
+<summary>dd/mm/aaaa HH:mm — TIPO</summary>
+
+- <o que foi criado/alterado, citando arquivos e decisões não óbvias>
+
+</details>
+```
+
+Entradas novas vão **no topo** da seção, logo abaixo do `## Execuções`. O `<summary>` carrega data,
+hora e tipo (`FEAT`, `FIX`, `REFACTOR`, `CHORE`…) — nada de heading `###`. Máximo 8 bullets por
+execução; específico sempre ("Criado `.../health-routes.ts` com rota `GET /health`", não
+"adicionada rota").
+
+## Heurísticas de quebra em tasks
+
+Quebre quando: a atividade toca frontend **e** backend; passaria de ~15 critérios de aceite;
+partes podem ser paralelizadas; uma parte está bloqueada e a outra não.
+
+Não quebre quando: o escopo é pequeno e coeso; as tasks resultantes teriam menos de 3 critérios.
+
+Posição no array `pages`: dependente depois da dependência; backend antes de frontend;
+integração/E2E por último.