Skill: Versionamento

Localização: .cursor/skills/versionamento/SKILL.md Escopo: projeto (ativo apenas neste repositório) Ativação: automática quando o usuário solicita commit, release, tag, CHANGELOG ou incremento de versão

---

Propósito

A skill versionamento garante que todo commit e release do projeto SinergIA siga um processo padronizado e rastreável, cobrindo desde a inspeção de arquivos staged até a criação de tags Git anotadas.

---

Fluxo principal

Quando o usuário pede commit ou release, o agente executa nesta ordem:

1. Inspecionar staged — verificar o que está e o que não deve estar
2. Determinar tipo de mudança — definir o escopo SemVer
3. Redigir mensagem — padrão Conventional Commits em português
4. Atualizar versão — nos arquivos de versão do projeto
5. Atualizar CHANGELOG — antes do commit
6. Commitar e tagear — commit + tag anotada (em releases)

---

1. Verificação de arquivos staged

Antes de qualquer commit, o agente verifica que nenhum dos itens abaixo está staged:

Categoria	Exemplos bloqueados
Segredos / credenciais	.env, *.pem, *.key, secrets.*, credentials.*
Build / compilação	dist/, build/, target/, *.class, *.pyc, __pycache__/
Dependências	node_modules/, vendor/, .venv/, venv/
IDE / OS	.idea/, .vscode/, .DS_Store, Thumbs.db
Logs / temporários	*.log, *.tmp, *.bak, TEST*.xml
Mídia pesada	*.mp4, *.avi, *.mov, *.tiff, *.flv, *.wmv
Artefatos empacotados	*.jar, *.war, *.exe, *.app

---

2. Versionamento Semântico (SemVer)

Incremento	Quando usar	Exemplo
MAJOR	Breaking change — quebra compatibilidade	1.x.x → 2.0.0
MINOR	Nova funcionalidade retrocompatível	1.2.x → 1.3.0
PATCH	Correção de bug retrocompatível	1.2.3 → 1.2.4

---

3. Mensagem de commit — Conventional Commits

Formato:

<tipo>(<escopo>): <descrição curta>

[corpo opcional — explica o porquê, não o quê]

[rodapé opcional: BREAKING CHANGE, refs a issues]

Tipos válidos:

Tipo	Uso
feat	Nova funcionalidade
fix	Correção de bug
docs	Apenas documentação
refactor	Refatoração sem nova feature nem bugfix
test	Adição ou correção de testes
chore	Tarefas de manutenção (CI, deps, config)
style	Formatação, espaçamento
perf	Melhoria de desempenho
ci	Mudanças em pipelines
build	Sistema de build, dependências externas
revert	Reverte commit anterior

Regras: imperativo, minúsculo, sem ponto final, máximo 72 caracteres, em português.

---

4. Arquivos de versão a atualizar (em releases)

Arquivo	Campo
package.json	"version"
pubspec.yaml	version:
pyproject.toml	version =
pom.xml	<version>
docs/projeto SinergIA.md	Tabela de histórico de versões

---

5. CHANGELOG

Atualizar CHANGELOG.md na raiz antes de cada release. Estrutura padrão Keep a Changelog:

## [X.Y.Z] — YYYY-MM-DD

### Adicionado
### Alterado
### Corrigido
### Removido
### Breaking Changes

---

6. Tags Git

git tag -a vX.Y.Z -m "release: vX.Y.Z — <resumo>"
git push origin vX.Y.Z

• Sempre tags anotadas (-a), nunca leves
• Formato: vMAJOR.MINOR.PATCH

---

7. Checklist de commit

- [ ] Nenhum arquivo proibido staged
- [ ] Tipo e escopo do commit definidos
- [ ] Mensagem segue Conventional Commits em português
- [ ] CHANGELOG atualizado (se release)
- [ ] Versão incrementada nos arquivos aplicáveis (se release)
- [ ] Tag criada e enviada (se release)

---

Referências: Conventional Commits · SemVer · Keep a Changelog