Gentle-IA — Habilidade de Branch & PR

Gentle IA — Habilidade de Branch & PR

Quando Usar

Carregue esta habilidade sempre que precisar:

• Criar um branch para uma nova correção ou funcionalidade
• Abrir um pull request em Gentleman-Programming/gentle-ai
• Preparar alterações para revisão

Regras Críticas

1. Cada PR DEVE vincular um problema aprovado — Closes/Fixes/Resolves #<N> no corpo do PR, e esse problema DEVE ter status:approved. PRs sem isso são rejeitados automaticamente pela CI.
2. Categorização comum type:* — A CI rejeita zero ou vários labels type:*. Direcione-o através do contrato de workflow canônico de criação de problemas: uma instrução humana direta atual vincula o alvo/ação exatos, a capacidade do host-alvo é verificada, e usa uma mutação limitada e leitura do host-alvo; caso contrário, aguarde sem mutação.
3. Etiquetas de política protegidas — Adicionar ou remover status:approved ou size:exception requer autoridade de política verificada de um mantenedor do repositório host-alvo ou de um aprovador autorizado pelo repositório para o alvo/ação exatos, além de viewerPermission MAINTAIN ou ADMIN do ator autenticado no host-alvo. size:exception adicionalmente exige uma justificativa documentada de estouro de orçamento.
4. Orçamento de revisão de 400 linhas — mantenha os PRs dentro de 400 linhas alteradas (additions + deletions) ou documente a justificativa necessária para um label size:exception.
5. As verificações automatizadas devem passar — veja a tabela de Verificações Automatizadas abaixo.
6. Sem trailers Co-Authored-By — nunca adicione atribuição de IA aos commits.
7. Sem push forçado para main/master — branch protegido.

Fluxo de Trabalho

1. Confirme que o problema tem status:approved
   gh issue view <N> --repo Gentleman-Programming/gentle-ai

2. Crie um branch a partir do main usando a convenção de nomenclatura abaixo

3. Implemente as alterações seguindo as especificações e o design

4. Execute as verificações localmente (formatação + unitários + E2E)

5. Faça commit usando o formato Conventional Commits

6. Abra um PR referenciando o problema
   → Declare exatamente UM resultado type:* no corpo do PR
   → Use o contrato de workflow canônico de criação de problemas antes de qualquer mutação de label do PR
   → Preencha o corpo do PR usando o template

7. Todas as verificações automatizadas devem passar antes do merge

---

Nomenclatura de Branches

Os nomes dos branches devem corresponder a este padrão:

^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$

Tipo	Exemplo
feat/	feat/user-login
fix/	fix/duplicate-observation-insert
docs/	docs/api-reference-update
refactor/	refactor/extract-query-sanitizer
chore/	chore/bump-bubbletea-v0.26
style/	style/fix-linter-warnings
perf/	perf/optimize-catalog-loading
test/	test/add-pipeline-coverage
build/	build/update-goreleaser-config
ci/	ci/add-e2e-docker-job
revert/	revert/undo-model-picker-change

Regras:

• Tudo em minúsculas
• Use hífens, pontos ou sublinhados como separadores (sem espaços, sem maiúsculas)
• A descrição deve ser curta e descritiva

---

Formato do Corpo do PR

O corpo do PR deve seguir o template em .github/PULL_REQUEST_TEMPLATE.md. Todas as seções são obrigatórias, a menos que marcadas como opcionais.

## 🔗 Problema Vinculado

Closes #<N>

## 🏷️ Tipo de PR

- [ ] `type:bug` — Correção de bug (mudança não disruptiva que corrige um problema)
- [ ] `type:feature` — Nova funcionalidade (mudança não disruptiva que adiciona funcionalidade)
- [ ] `type:docs` — Apenas documentação
- [ ] `type:refactor` — Refatoração de código (sem mudanças funcionais)
- [ ] `type:chore` — Mudanças de build, CI ou ferramentas
- [ ] `type:breaking-change` — Mudança disruptiva

## 📝 Resumo

<!-- Descrição clara do que este PR faz e por quê. -->

## 📂 Alterações

| Arquivo / Área | O Que Mudou |
|----------------|-------------|
| `path/to/file` | Breve descrição |

## 🧪 Plano de Testes

**Testes Unitários**
\`\`\`bash
go test ./...
\`\`\`

**Formatação Go**
\`\`\`bash
go run ./internal/gofmtcheck
\`\`\`

**Testes E2E** (Docker necessário)
\`\`\`bash
cd e2e && ./docker-test.sh
\`\`\`

- [ ] Testes unitários passam (`go test ./...`)
- [ ] Formatação Go passa (`go run ./internal/gofmtcheck`)
- [ ] Testes E2E passam (`cd e2e && ./docker-test.sh`)
- [ ] Testado manualmente localmente

## ✅ Checklist do Contribuidor

- [ ] PR está vinculado a um problema com `status:approved`
- [ ] PR permanece dentro de 400 linhas alteradas, ou a justificativa `size:exception` e a autoridade de política verificada estão documentadas
- [ ] A leitura da API confirma exatamente um label `type:*` apropriado neste PR
- [ ] Testes unitários passam (`go test ./...`)
- [ ] Testes E2E passam (`cd e2e && ./docker-test.sh`)
- [ ] Atualizei a documentação se necessário
- [ ] Meus commits seguem o formato Conventional Commits
- [ ] Meus commits não incluem trailers `Co-Authored-By`

---

Verificações Automatizadas

Estas verificações são executadas em cada PR e todas devem passar antes do merge:

Verificação	O Que Verifica	Como Corrigir
Verificar Carga Cognitiva do PR	PR permanece dentro de 400 linhas alteradas (additions + deletions) ou tem size:exception	Divida o PR, ou documente a justificativa size:exception e verifique a autoridade de política antes de sua ação de workflow canônica
Verificar Referência ao Problema	Corpo do PR contém Closes/Fixes/Resolves #N	Adicione Closes #<N> ao corpo do PR
Verificar se o Problema tem status:approved	O problema vinculado tem o label necessário	Use o contrato de workflow canônico de criação de problemas apenas quando uma instrução direta atual e uma autorização de capacidade do host-alvo permitirem a ação exata; caso contrário, aguarde
Verificar se o PR tem Label type:*	Exatamente um label type:* é aplicado ao PR	Use o contrato de workflow canônico de criação de problemas apenas quando uma instrução direta atual e uma capacidade do host-alvo autorizarem a ação exata; caso contrário, aguarde
Testes Unitários	go test ./... passa	Corrija testes com falha antes de enviar
Formatação Go	go run ./internal/gofmtcheck passa	Formate arquivos Go mal formatados antes de enviar
Testes E2E	cd e2e && ./docker-test.sh passa	Corrija cenários E2E com falha antes de enviar

---

Conventional Commits

As mensagens de commit devem corresponder a este padrão:

^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+

Formato

<tipo>(<escopo-opcional>)!: <descrição>

[corpo opcional]

[rodapé opcional]

Tipos Permitidos

Tipo	Propósito	Label do PR
feat	Nova funcionalidade	type:feature
fix	Correção de bug	type:bug
docs	Apenas documentação	type:docs
refactor	Mudança de código (sem mudança de comportamento)	type:refactor
chore	Manutenção, dependências, ferramentas	type:chore
style	Formatação, linting (sem mudança de lógica)	type:chore
perf	Melhoria de desempenho	type:feature
test	Adicionar ou atualizar testes	type:chore
build	Sistema de build ou dependências externas	type:chore
ci	Configuração de CI	type:chore
revert	Reverte um commit anterior	corresponde ao tipo revertido

Mudanças Disruptivas

Adicione ! após o tipo/escopo:

feat(cli)!: renomear a flag --config para --config-file

BREAKING CHANGE: a flag --config foi renomeada para --config-file.

Mudanças disruptivas mapeiam para o label type:breaking-change.

Exemplos

feat(tui): adicionar barra de progresso às etapas de instalação
fix(agent): corrigir detecção do Claude Code no macOS
docs: atualizar guia de contribuição
chore(deps): atualizar bubbletea para v0.26
refactor(pipeline): extrair executor de etapas
style: corrigir avisos de lint no pacote catalog
perf(system): armazenar em cache o resultado de detecção do SO
test(installer): adicionar cobertura para execução de etapa do catalog
build: atualizar config do goreleaser para arm64
ci: dividir jobs de teste unitário e E2E
revert: desfazer redesign do seletor de modelo
feat(cli)!: alterar caminho padrão de configuração

---

Comandos

Configuração

# Confirme que o problema está aprovado antes de começar
gh issue view <N> --repo Gentleman-Programming/gentle-ai

# Crie o branch
git checkout main && git pull
git checkout -b fix/<descrição-curta>

Testes Locais

# Testes unitários
go test ./...

# Formatação Go
go run ./internal/gofmtcheck

# Testes unitários — pacote específico
go test ./internal/tui/...

# Testes unitários — verboso
go test -v ./...

# Testes E2E (Docker deve estar executando)
cd e2e && ./docker-test.sh

Abrir um PR

gh pr create \
  --repo Gentleman-Programming/gentle-ai \
  --title "fix(agent): corrigir detecção do Claude Code no Linux" \
  --body "$(cat <<'EOF'
## 🔗 Problema Vinculado

Closes #42

## 🏷️ Tipo de PR

- [x] \`type:bug\` — Correção de bug (mudança não disruptiva que corrige um problema)

## 📝 Resumo

Corrige a falha de detecção do binário Claude Code no Linux quando HOME não está definido.

## 📂 Alterações

| Arquivo / Área | O Que Mudou |
|----------------|-------------|
| \`internal/agents/claude.go\` | Adicionado fallback da variável de ambiente HOME |

## 🧪 Plano de Testes

- [x] Testes unitários passam (\`go test ./...\`)
- [x] Testes E2E passam (\`cd e2e && ./docker-test.sh\`)
- [x] Testado manualmente localmente

## ✅ Checklist do Contribuidor

- [x] PR está vinculado a um problema com \`status:approved\`
- [x] PR permanece dentro de 400 linhas alteradas, ou a justificativa \`size:exception\` e a autoridade de política verificada estão documentadas
- [x] A leitura da API confirma exatamente um label \`type:*\` apropriado neste PR
- [x] Testes unitários passam (\`go test ./...\`)
- [x] Testes E2E passam (\`cd e2e && ./docker-test.sh\`)
- [x] Atualizei a documentação se necessário
- [x] Meus commits seguem o formato Conventional Commits
- [x] Meus commits não incluem trailers \`Co-Authored-By\`
EOF
)"

Verificar Status do PR

gh pr checks --repo Gentleman-Programming/gentle-ai <número-do-PR>
gh pr view --repo Gentleman-Programming/gentle-ai <número-do-PR>