@mir-code/specs-platform 1.0.1

package/assets/template/.agents/README.md

@@ -0,0 +1,123 @@
+# Agentes e skills (fonte única)
+
+Este diretório é a **fonte de verdade** dos subagentes e skills do projeto. Claude Code e Cursor leem
+os mesmos arquivos via symlinks, criados pelo instalador da Specs Platform:
+
+```
+.agents/
+├── agents/     ← launchers de 15 linhas          → .claude/agents, .cursor/agents
+├── skills/     ← todo o conteúdo (processo + conhecimento) → .claude/skills, .cursor/skills
+├── scripts/    ← validadores determinísticos     (fora de qualquer symlink)
+├── project.md  ← configuração deste projeto      (fora de qualquer symlink)
+├── README.md   ← este arquivo                    (fora de qualquer symlink)
+└── RUNTIME.md  ← mapa de tools Claude Code ↔ Cursor (fora de qualquer symlink)
+```
+
+| Consumidor | Agentes | Skills |
+|---|---|---|
+| Claude Code | `.claude/agents/` → `.agents/agents/` | `.claude/skills/` → `.agents/skills/` |
+| Cursor | `.cursor/agents/` → `.agents/agents/` | `.cursor/skills/` → `.agents/skills/` |
+
+> **Por que `agents/` e `skills/` são irmãs, e não aninhadas.** Claude Code e Cursor varrem o
+> diretório de agentes **recursivamente** e registram todo `.md` com frontmatter `name` +
+> `description` como subagente. Se os symlinks apontassem para `.agents/` inteira, as skills
+> apareceriam **também** na lista de subagentes: descrições duplicadas no system prompt de toda
+> sessão e risco de delegar `subagent_type: test-strategy` em vez de carregar a skill. Não mova
+> `skills/` para dentro de `agents/`, nem reaponte os symlinks para a raiz de `.agents/`.
+
+## Primeiro passo depois de instalar: preencher `project.md`
+
+As skills são **agnósticas ao projeto** — contêm método, não valores. Elas não sabem a stack, os
+caminhos dos pacotes, os comandos de teste, a biblioteca de UI nem a ferramenta de protótipo.
+
+Tudo isso vive em **`project.md`**, que chega como formulário em branco. Enquanto um campo estiver
+`<preencher>`, a skill que depende dele **para e pergunta** em vez de adivinhar. Campo que não se
+aplica: escreva `n/a`.
+
+| Seção de `project.md` | Consumida por |
+|---|---|
+| Identidade · Stack | `feature-runner`, `refinement` |
+| Pacotes, testes e comandos | `test-strategy` (matriz de cobertura e comandos de gate) |
+| Convenções de código | `execution-protocol`, `feature-runner` |
+| Design e UI | `ui-standards` (skill opcional) |
+| Segurança de inputs | `input-security` (skill opcional) |
+| Ferramentas visuais | `prototype-check` |
+| Documentação e processo | `spec-writing`, `discovery-writing`, `drawing-writing` |
+| Scratch e temporários | `verification` (prefixo do worktree descartável) |
+
+Ajuste também `CODE_EXTENSIONS` em `scripts/validate-spec.mjs`, se a stack usar outras extensões.
+
+## O conteúdo vive nas skills; o agente é só um launcher
+
+Cada arquivo de `agents/` tem 15 linhas: frontmatter (`name`, `description`, `tools`) e uma frase
+mandando carregar a skill de mesmo nome. **Nenhuma regra é duplicada ali.**
+
+Isso entrega três coisas ao mesmo tempo:
+
+- **Divulgação progressiva.** O `SKILL.md` de uma skill de processo traz princípios e o mapa de
+  fases; o detalhe de cada fase mora em `references/`, lido só quando a fase começa.
+- **Contexto isolado quando importa.** Delegar via `Agent` / `Task` com `subagent_type` continua
+  funcionando e continua nascendo com contexto limpo.
+- **Invocação direta quando não importa.** `/feature-runner` (Claude Code) ou ler o `SKILL.md`
+  (Cursor) roda o mesmo processo sem subagente.
+
+**Para mudar comportamento, edite a skill.** O arquivo do agente só muda se o `description` (que
+governa a delegação proativa) ou a lista de `tools` mudar.
+
+## As skills
+
+### Processo — o que fazer, em que ordem
+
+| Skill | Papel |
+|---|---|
+| `refinement` | descrição livre → spec documentada em `.specs/specs/` |
+| `feature-runner` | spec → código, halt para code review humano |
+| `refinement-runner` | descrição livre → código direto, sem escrever spec |
+| `discovery-agent` | problema aberto → RFC/spike/ADR em `.specs/discoveries/` |
+| `drawing-agent` | pedido de diagrama → desenho Mermaid em `.specs/drawings/` |
+| `execution-protocol` | protocolo comum aos dois runners: princípios invioláveis, blast radius, git, halt, complete |
+
+### Conhecimento — como fazer bem
+
+| Skill | Cobre |
+|---|---|
+| `spec-writing` | formato da página de spec, diagrama Mermaid, blocos `<details>`, `overview.md`, frontmatter, registro de Execuções |
+| `requirements-closure` | critérios de aceite em EARS, IDs de requisito, sweep das 9 dimensões implícitas, portão de fechamento |
+| `test-strategy` | matriz de cobertura por camada, os três gates, co-location, Test Adequacy Review (A–D) |
+| `verification` | Verifier independente, evidence-or-zero, sensor de discriminação em worktree descartável |
+| `discovery-writing` | tipos (rfc/spike/adr/note), frontmatter, estrutura por tipo, `meta.json` |
+| `drawing-writing` | formato do arquivo de desenho e o `meta.json` de `.specs/drawings/` |
+| `mermaid-diagramming` | sintaxe e estética do Mermaid, checklist antes de gravar |
+| `prototype-check` | identificar a ferramenta de protótipo e consultá-la antes de implementar |
+
+### Skills opcionais, não incluídas
+
+`ui-standards` (padrões de UI) e `input-security` (sanitização de inputs) são referenciadas pelas
+skills de processo como **condicionais**: se o projeto as adotar, elas são carregadas; se não
+existirem, o agente segue sem elas. Para adotá-las, copie-as de um projeto que já as tenha e
+preencha as seções correspondentes de `project.md`.
+
+## Gates determinísticos
+
+O que é estrutural roda por código, não por memória:
+
+```bash
+node .agents/scripts/validate-spec.mjs .specs/specs/<slug>/feat-<slug>-<task>.md
+node .agents/scripts/check-commit.mjs --message "feat(login): tela de login"
+```
+
+Saída ≠ 0 significa **pare e corrija**.
+
+## Levar esta estrutura para outro projeto
+
+A Specs Platform já faz isso: `specs install` instala `.agents/` e cria os symlinks. Manualmente:
+
+1. Copie `.agents/` inteira.
+2. Crie os symlinks: `.claude/agents` → `../.agents/agents`, `.claude/skills` → `../.agents/skills`,
+   e o mesmo para `.cursor/`.
+3. **Preencha `project.md`.** Nenhuma skill precisa ser tocada.
+
+O que **não** é configurável, por ser o método em si: a estrutura `.specs/specs/`,
+`.specs/discoveries/` e `.specs/drawings/`, o `.specs/STATE.md` com `AD-NNN`, o ciclo
+halt → ajustar → complete, a notação EARS dos critérios de aceite e o Test Adequacy Review. Quem
+adota estes agentes adota este processo — é o que eles são.

package/assets/template/.agents/RUNTIME.md

@@ -0,0 +1,64 @@
+# Runtime: Claude Code e Cursor
+
+Use este mapa quando um prompt citar uma tool ou fluxo de outro produto. O **comportamento** é o mesmo; muda só o nome da tool.
+
+## Perguntas estruturadas ao usuário
+
+| Claude Code | Cursor |
+|---|---|
+| `AskUserQuestion` | `AskQuestion` |
+
+Sempre 2–4 opções concretas; marque "(Recomendado)" quando fizer sentido.
+
+## Edição de arquivos
+
+| Claude Code | Cursor |
+|---|---|
+| `Edit` | `StrReplace` (ou `Write` para arquivo novo) |
+| `Write` | `Write` |
+| `Read` | `Read` |
+| `Glob` / `Grep` | `Glob` / `Grep` |
+| `Bash` | `Shell` |
+
+Prefira tools de arquivo em vez de `cat`/`grep`/`sed` no terminal.
+
+## Subagentes
+
+| Claude Code | Cursor |
+|---|---|
+| `Agent` com `subagent_type` | `Task` com `subagent_type` |
+
+Exemplos: `feature-runner`, `refinement`, `refinement-runner`, `discovery-agent`, `drawing-agent`,
+mais os genéricos do produto (`explore`, `generalPurpose`).
+
+Para tools de protótipo e de E2E (normalmente indisponíveis no agente pai): delegue a um subagente
+com o MCP correspondente, como descrito em `prototype-check`.
+
+## Skills
+
+| Claude Code | Cursor |
+|---|---|
+| `Skill` tool ou `/nome-da-skill` | Ler `.agents/skills/<nome>/SKILL.md` (ou symlink `.cursor/skills/`) |
+
+Skills listadas no frontmatter do agente devem ser **lidas por completo** antes da fase que as exige.
+
+### `references/` — divulgação progressiva
+
+Uma skill de processo tem `SKILL.md` curto (princípios + mapa de fases) e arquivos em
+`references/` com o detalhe de cada fase. **Carregue a referência no momento em que a fase começa,
+e leia-a até o fim** — nunca aja sobre leitura parcial, e nunca pré-carregue todas.
+
+Os caminhos em `references/` são relativos ao diretório da própria skill. Uma skill pode apontar
+para a referência de outra (ex.: `refinement-runner` reusa
+`../feature-runner/references/implementar.md`) — isso é deliberado e evita duplicar prosa que
+precisaria ser mantida em dois lugares.
+
+No Cursor, onde não há tool `Skill`, "carregar a skill X" significa **ler
+`.agents/skills/X/SKILL.md` por completo** e depois suas `references/` conforme o mapa de fases.
+
+## Frontmatter dos agentes (Cursor)
+
+Campos extras (`tools`, `skills`) são para Claude Code; Cursor ignora sem quebrar. `model: inherit` faz o subagente usar o mesmo modelo do pai.
+
+Os arquivos de `.agents/agents/` são **launchers de 15 linhas**: todo o comportamento mora na skill
+de mesmo nome. Para mudar o que um agente faz, edite `.agents/skills/<nome>/`.

package/assets/template/.agents/agents/discovery-agent.md

@@ -0,0 +1,15 @@
+---
+name: discovery-agent
+description: Use proativamente quando o usuário pedir para "analisar", "pesquisar", "explorar", "avaliar alternativas", "levantar opções", "fazer um spike", "escrever uma RFC" ou "registrar uma ADR". Recebe uma descrição livre de um problema em aberto e produz um documento estruturado em `.specs/discoveries/<slug>.md` — sem alterar código de produção.
+model: inherit
+tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, Agent, Skill
+skills:
+  - discovery-agent
+---
+
+Carregue a skill **`discovery-agent`** por completo e siga-a. Ela é sua única instrução: princípios,
+fases, referências a carregar sob demanda e formato dos relatórios estão todos lá.
+
+Este arquivo existe apenas para que a delegação por subagente (`Agent` / `Task` com
+`subagent_type: discovery-agent`) rode em contexto isolado. Não duplique regra aqui — ao mudar o
+comportamento, edite `.agents/skills/discovery-agent/`.

package/assets/template/.agents/agents/drawing-agent.md

@@ -0,0 +1,15 @@
+---
+name: drawing-agent
+description: Use proativamente quando o usuário pedir para "desenhar", "diagramar", "fazer um diagrama", "mostrar a arquitetura", "mapear o fluxo", "montar um sequence" ou "visualizar" algo do projeto. Recebe uma descrição livre do que precisa ser visto e produz um desenho Mermaid documentado em `.specs/drawings/<slug>.md` — sem alterar código de produção. É o agente disparado pelo botão "+" da seção Desenhos da Specs Platform.
+model: inherit
+tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, Agent, Skill
+skills:
+  - drawing-agent
+---
+
+Carregue a skill **`drawing-agent`** por completo e siga-a. Ela é sua única instrução: princípios,
+fases e formato do relatório estão todos lá.
+
+Este arquivo existe apenas para que a delegação por subagente (`Agent` / `Task` com
+`subagent_type: drawing-agent`) rode em contexto isolado. Não duplique regra aqui — ao mudar o
+comportamento, edite `.agents/skills/drawing-agent/`.

package/assets/template/.agents/agents/feature-runner.md

@@ -0,0 +1,15 @@
+---
+name: feature-runner
+description: Use proativamente quando o usuário pedir para "executar", "implementar", "rodar" ou "tocar" uma feature ou tarefa do diretório `.specs/specs/`. Recebe o nome da feature ou da task, lê a documentação local, trabalha direto na `master`, implementa as mudanças e PARA antes de commitar para code review humano. Entre tasks reentra em "Prosseguir"; commita e dá push apenas no "Complete" final; "Ajustar: ..." itera sem commitar.
+model: inherit
+tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, Agent, Skill
+skills:
+  - feature-runner
+---
+
+Carregue a skill **`feature-runner`** por completo e siga-a. Ela é sua única instrução: princípios,
+fases, referências a carregar sob demanda e formato dos relatórios estão todos lá.
+
+Este arquivo existe apenas para que a delegação por subagente (`Agent` / `Task` com
+`subagent_type: feature-runner`) rode em contexto isolado. Não duplique regra aqui — ao mudar o
+comportamento, edite `.agents/skills/feature-runner/`.

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

@@ -0,0 +1,15 @@
+---
+name: refinement-runner
+description: Use proativamente quando o usuário pedir para "refinar e executar", "refinar e já implementar", "fazer direto" ou descrever uma atividade que ele quer ver implementada sem passar por documentação de spec. Esgota todas as dúvidas antes de tocar em código, implementa e PARA antes de commitar para code review humano. Commita apenas no "Complete" explícito. Não cria nem altera documentos em `.specs/specs/`.
+model: inherit
+tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, Agent, Skill
+skills:
+  - refinement-runner
+---
+
+Carregue a skill **`refinement-runner`** por completo e siga-a. Ela é sua única instrução: princípios,
+fases, referências a carregar sob demanda e formato dos relatórios estão todos lá.
+
+Este arquivo existe apenas para que a delegação por subagente (`Agent` / `Task` com
+`subagent_type: refinement-runner`) rode em contexto isolado. Não duplique regra aqui — ao mudar o
+comportamento, edite `.agents/skills/refinement-runner/`.

package/assets/template/.agents/agents/refinement.md

@@ -0,0 +1,15 @@
+---
+name: refinement
+description: Use proativamente quando o usuário pedir para "refinar", "detalhar", "especificar", "quebrar" ou "planejar" uma atividade, feature ou tarefa. Recebe uma descrição livre, se contextualiza com as features existentes em `.specs/specs/`, analisa o estado atual do código e produz uma task (ou feature completa) documentada — pronta para ser executada pelo `feature-runner`.
+model: inherit
+tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, Agent, Skill
+skills:
+  - refinement
+---
+
+Carregue a skill **`refinement`** por completo e siga-a. Ela é sua única instrução: princípios,
+fases, referências a carregar sob demanda e formato dos relatórios estão todos lá.
+
+Este arquivo existe apenas para que a delegação por subagente (`Agent` / `Task` com
+`subagent_type: refinement`) rode em contexto isolado. Não duplique regra aqui — ao mudar o
+comportamento, edite `.agents/skills/refinement/`.

package/assets/template/.agents/project.md

@@ -0,0 +1,158 @@
+# Configuração do projeto
+
+**Preencha este arquivo ao instalar a Specs Platform.** Ele é a fonte única dos valores concretos
+que as skills consomem: as skills contêm o *método*, este arquivo contém o *que este projeto usa*.
+Nenhuma skill precisa ser editada.
+
+Enquanto uma seção estiver como `<preencher>`, a skill que depende dela vai **parar e perguntar** em
+vez de adivinhar. Seção que não se aplica: escreva `n/a` — a skill registra "não se aplica a este
+projeto" e segue.
+
+---
+
+## Identidade
+
+| Campo | Valor |
+|---|---|
+| Nome | `<preencher>` |
+| Domínio | `<uma linha: o que o produto faz>` |
+| Idioma do código | `<ex.: inglês — identificadores, comentários, rotas, colunas, enums>` |
+| Idioma do conteúdo | `<ex.: pt-BR — UI, mensagens ao usuário, docs, commits>` |
+
+## Stack
+
+| Camada | Tecnologia |
+|---|---|
+| Repositório | `<ex.: monorepo Turborepo + pnpm · ou repo único>` |
+| Frontend | `<ex.: Next.js 16 + Tailwind · ou n/a>` |
+| Backend | `<ex.: Fastify + TypeScript · Spring Boot · FastAPI>` |
+| Banco | `<ex.: PostgreSQL + Prisma>` |
+| Lint/format | `<ex.: Biome · ESLint + Prettier · Spotless>` |
+| Runner de teste | `<ex.: vitest · jest · JUnit · pytest>` |
+
+## Pacotes, testes e comandos
+
+Usado por `test-strategy` (matriz de cobertura e gates).
+
+Uma linha por camada de código do projeto. O que importa é que cada camada tenha **onde o teste
+mora** e **qual comando o roda**.
+
+| Camada de código | Tipo de teste | Onde o teste mora | Comando |
+|---|---|---|---|
+| `<ex.: use case / regra de negócio>` | unit | `<path>` | `<comando>` |
+| `<ex.: adapter / repositório>` | integration | `<path>` | `<comando>` |
+| `<ex.: rota / controller>` | integration (contrato) | `<path>` | `<comando>` |
+| `<ex.: utilitário compartilhado>` | unit | `<path>` | `<comando>` |
+| `<ex.: tela / componente>` | E2E | via `prototype-check` | `<sub-agente com a tool de E2E>` |
+| `<ex.: entidade, DTO, tipo, config>` | nenhum | — | só o gate de build |
+
+**Comandos de gate**
+
+| Nível | Comando |
+|---|---|
+| rápido | `<comando de um pacote só>` |
+| completo | `<comando de vários pacotes>` |
+| build | `<comando de lint/build>` + os testes dos pacotes tocados |
+
+**Flag obrigatória:** `<ex.: -- --run, para o runner não entrar em watch mode>` · `n/a` se não houver.
+
+**Comando que roda o repositório inteiro** (caro, só no gate build): `<preencher>`
+
+**Referência de rigor** — o módulo cujo padrão de teste é o mais alto do repositório, e que novos
+testes não devem subverter: `<path · ou n/a se o repo ainda não tem testes>`
+
+**Convenções de teste:** `<ex.: arquivo em kebab-case, código em inglês, path conforme a matriz>`
+
+## Convenções de código
+
+Usado por `execution-protocol` e `feature-runner`.
+
+| Item | Valor |
+|---|---|
+| Formatação | `<ex.: Biome — singleQuote, semicolons: asNeeded, lineWidth 100, 2 espaços>` |
+| Tipagem | `<ex.: TypeScript strict>` |
+| Nome de arquivo | `<ex.: kebab-case em todo o repositório>` |
+| Comando de lint + format | `<preencher>` |
+| Comando de build completo | `<preencher — e avise se for caro>` |
+
+**Onde procurar reuso antes de criar** (utilitário, tipo, componente, hook):
+`<liste os diretórios>`
+
+**Libs cuja versão costuma mudar decisão** (consulte a doc atual antes de decidir):
+`<liste · ou n/a>`
+
+## Design e UI
+
+Usado por `ui-standards`, se o projeto adotar essa skill. `n/a` para projeto sem frontend.
+
+| Item | Valor |
+|---|---|
+| Primitivos headless | `<ex.: Radix UI · Headless UI · n/a>` |
+| Framework de CSS | `<ex.: Tailwind v4 · CSS Modules>` |
+| Exemplo de token | `<ex.: bg-brand-yellow — nunca bg-[var(--color-brand-yellow)]>` |
+| API de toast | `<ex.: notify de @/components/ui/toast>` |
+| Formulários | `<ex.: react-hook-form + Zod, mode: 'onTouched'>` |
+| Textos estáticos | `<ex.: CMS via getCmsText() · arquivo de i18n · hardcoded>` |
+| Breakpoints | `<ex.: Desktop 1440 · Tablet 768 · Mobile 375 (mínimo testável: 320px)>` |
+
+**Equivalências px → escala do framework:** `<preencher se o framework tiver escala própria>`
+
+## Segurança de inputs
+
+Usado por `input-security`, se o projeto adotar essa skill.
+
+| Item | Valor |
+|---|---|
+| Módulo das funções | `<path · ou "criar em <path>" se ainda não existir>` |
+| Código de erro | `<ex.: INPUT_NOT_ALLOWED ⇒ HTTP 400 com mensagem genérica>` |
+| Validação | `<ex.: schemas Zod — .transform(sanitize*) + .refine(assert*); body .strict()>` |
+| ORM | `<ex.: Prisma — parametriza queries, não substitui a camada defensiva>` |
+
+**Funções disponíveis:** `<liste as que já existem>`
+
+**Dados sensíveis deste domínio:** `<ex.: CPF nunca em claro no log; placa como hash truncado>`
+
+## Ferramentas visuais
+
+Usado por `prototype-check`.
+
+| Papel | Ferramenta | Observações |
+|---|---|---|
+| Protótipo | `<pencil · claude-design · figma · n/a>` | `<ex.: arquivos .pen são encriptados — só via MCP>` |
+| E2E de navegador | `<ex.: Playwright MCP · n/a>` | — |
+| Disponibilidade | `<ex.: ambas só em sub-agentes>` | delegue com `Agent` / `Task` + `subagent_type` |
+
+**Credenciais de teste E2E:** `<usuário / senha · ou aponte o .env.test>`
+
+**Health check do dev server:** `<ex.: curl na raiz do app>`
+
+**Override por feature:** o bloco `prototype` do `.specs/config.json` — sobrescrito pelo `meta.json`
+da feature quando ele declarar o seu — define a ferramenta de protótipo caso ela varie entre
+features. Valores suportados: `pencil` (arquivo `.pen`, consulta por MCP, tem node IDs) e
+`claude-design` (canvas endereçado por `url`, referência por nome de artboard). Sem bloco: o projeto
+não tem protótipo.
+
+## Documentação e processo
+
+Estes valores vêm da Specs Platform e normalmente **não mudam** entre projetos.
+
+| Item | Valor |
+|---|---|
+| Specs | `.specs/specs/<slug>/feat-<slug>-<task>.md` |
+| Discoveries | `.specs/discoveries/<slug>.md` |
+| Desenhos | `.specs/drawings/<slug>.md` |
+| Memória de projeto | `.specs/STATE.md` — `## Decisions` (`AD-NNN`) e `## Handoff` |
+| Renderização | Specs Platform (`@mir-code/specs-platform`) — sobe com `specs start`; troubleshooting em `SPECS.md` |
+| Convenções gerais | `CLAUDE.md`/`AGENTS.md` na raiz e em cada app |
+
+**Formato de commit:** `<ex.: tipo(escopo): descrição, com Refs: <caminho da spec>>`
+
+**Extensões de arquivo que contam como "path de código"** (usado pelo validador de spec, que proíbe
+citar path concreto na spec): `<ex.: ts, tsx, prisma, json, http>` — espelhe em `CODE_EXTENSIONS` de
+`.agents/scripts/validate-spec.mjs`.
+
+## Scratch e temporários
+
+| Item | Valor |
+|---|---|
+| Prefixo de worktree descartável | `<ex.: /tmp/<projeto>-sensor>` |

package/assets/template/.agents/scripts/check-commit.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Valida a mensagem de commit no formato definido em .agents/project.md:
+ *
+ *   <type>(<escopo>): <título da task>
+ *
+ *   Refs: .specs/specs/<slug>/feat-<slug>-<task>.md     (opcional, mas exigido em task de spec)
+ *   Task status: in-progress -> completed
+ *
+ * Uso:
+ *   node .agents/scripts/check-commit.mjs --message "feat(login): tela de login"
+ *   node .agents/scripts/check-commit.mjs --file .git/COMMIT_EDITMSG
+ *
+ * Como guarda de git (opcional, uma vez, a partir da raiz do repo):
+ *   printf '#!/bin/sh\nnode .agents/scripts/check-commit.mjs --file "$1"\n' > .git/hooks/commit-msg
+ *   chmod +x .git/hooks/commit-msg
+ */
+
+import { readFileSync } from 'node:fs'
+
+const TYPES = ['feat', 'fix', 'refactor', 'chore', 'docs', 'test', 'infra', 'build', 'ci', 'perf', 'style']
+const MAX_SUBJECT = 100
+
+const args = process.argv.slice(2)
+function arg(name) {
+  const i = args.indexOf(name)
+  return i === -1 ? null : args[i + 1]
+}
+
+let message = arg('--message')
+const file = arg('--file')
+if (file) message = readFileSync(file, 'utf8')
+if (!message) {
+  console.error('uso: check-commit.mjs --message "<msg>" | --file <caminho>')
+  process.exit(2)
+}
+
+const lines = message.split('\n').filter((l) => !l.startsWith('#'))
+const subject = (lines[0] ?? '').trim()
+const errors = []
+const warnings = []
+
+const m = subject.match(/^([a-z]+)(\(([a-z0-9][a-z0-9-]*)\))?(!)?: (.+)$/)
+if (!m) {
+  errors.push(
+    'assunto fora do formato `<type>(<escopo>): <descrição>` — escopo em kebab-case minúsculo',
+  )
+} else {
+  const [, type, , scope, , description] = m
+  if (!TYPES.includes(type)) errors.push(`tipo \`${type}\` inválido — use: ${TYPES.join(', ')}`)
+  if (!scope) warnings.push('sem escopo — prefira `<type>(<slug-da-feature>): ...`')
+  if (description.endsWith('.')) errors.push('descrição não termina com ponto final')
+  if (/^[A-Z]/.test(description) && !/^[A-Z]{2,}/.test(description))
+    warnings.push('descrição começa com maiúscula — prefira minúscula, salvo sigla')
+  if (subject.length > MAX_SUBJECT)
+    errors.push(`assunto com ${subject.length} caracteres (máximo ${MAX_SUBJECT})`)
+}
+
+if (lines.length > 1 && lines[1].trim() !== '')
+  errors.push('falta a linha em branco entre o assunto e o corpo')
+
+const body = lines.slice(1).join('\n')
+if (/BREAKING CHANGE/.test(body) && !/^[a-z]+(\([a-z0-9-]+\))?!:/.test(subject))
+  errors.push('corpo traz `BREAKING CHANGE:` mas o assunto não tem o `!` depois do tipo/escopo')
+
+for (const e of errors) console.error(`ERRO  ${e}`)
+for (const w of warnings) console.error(`aviso ${w}`)
+if (errors.length === 0 && warnings.length === 0) console.log('mensagem de commit OK')
+
+process.exit(errors.length > 0 ? 1 : 0)