Contribuir para o DeskcommCRM sem retrabalho

Quem contribui aqui quase nunca erra por falta de capacidade — erra por não saber a régua. A régua existe, mas está espalhada em três documentos (CLAUDE.md, CONTRIBUTING.md e o procedimento de triagem, com mais de 100 KB) e é aplicada depois do PR, por quem mantém. Este guia aplica a mesma régua antes, do seu lado, para o PR chegar pronto. Taxa histórica de recusa de PR de fork: zero. O que trava é retrabalho — e retrabalho se evita medindo.

Como você age

• Aconselha, não bloqueia. Você mede e mostra; só os hooks de git bloqueiam, e só o que é irreversível (push na main, migration sem a tripla). Uma pessoa que quer seguir mesmo assim segue — sabendo o que vai acontecer na triagem.
• Mede na fonte, nunca copia número. A lista de checks obrigatórios, quantas specs rodam e o que o CI cobre mudam toda semana; cada afirmação vem com o comando que a produziu.
• Declara o que não mediu. Um PR que diz "não rodei o e2e porque não tenho Docker" é melhor que um que marca tudo. O mantenedor prova o que ficou faltando; a régua pública é essa.
• Sabota antes de dizer "testado". Teste que não fica vermelho quando o conserto sai não guarda nada.

Passo 0 — quem está contribuindo

Este passo vem antes de trazer a main (Passo 1), então não conte com o script estar no clone: um fork anterior a 2026-09-10 ainda não o tem, e o guia pode ter vindo da instalação global. O comando abaixo procura o script na raiz do clone (vale de qualquer subpasta dele) e, se não achar, nas três pastas globais em que o instalar-guias.sh põe os guias. Cole como está, de onde você estiver:

r="$(git rev-parse --show-toplevel 2>/dev/null)"; s=""
for g in ${r:+"$r/.agents/skills"} ~/.claude/skills ~/.agents/skills ~/.gemini/config/skills; do
  [ -f "$g/deskcomm-contribuir/scripts/quem-sou.sh" ] && { s="$g/deskcomm-contribuir/scripts/quem-sou.sh"; break; }
done
if [ -n "$s" ]; then bash "$s"; else
  echo "NÃO MEDIDO — não achei o quem-sou.sh ${r:+no clone $r }nem nas pastas globais dos guias." >&2
  echo "Instale os guias pelo comando de uma linha do README (https://github.com/melgarafael/DeskcommCRM#readme) e rode de novo." >&2
  false
fi

A resposta vem da pasta onde você rodou, não de onde o script mora: fora de um clone ela é contribuidor — fora de um clone git, e se afina sozinha assim que o terminal estiver dentro do clone.

A resposta decide o resto do guia, e são três:

• Começa com mantenedor: este guia fica quieto — o mantenedor tem o próprio ritual (triagem, gov-loop) e hooks próprios em loop/hooks. Só siga se a pessoa pedir por nome.
• Começa com contribuidor: siga. O script diz por quê (e-mail do git no .mailmap, conta do gh, o origin ser fork).
• Começa com NÃO MEDIDO (e o bloco sai com erro): o script não está nem no clone nem nas pastas globais — um fork anterior a 2026-09-10 sem a instalação global, ou um terminal fora de clone sem ela. Ninguém foi classificado: não trate a pessoa como mantenedor nem como contribuidor por essa saída. Instale os guias pelo comando de uma linha do README, que a própria saída aponta, e rode este passo de novo — vale de qualquer pasta, inclusive num fork cujo main ainda não tem o script.

Passo 1 — a âncora: origin/main, nunca o disco

git fetch origin
MAIN=$(git rev-parse --short origin/main); echo "main=$MAIN"
B=$(git merge-base origin/main HEAD)
echo "atraso=$(git rev-list --count $B..origin/main) proprios=$(git rev-list --count $B..HEAD)"
comm -12 <(git diff --name-only $B origin/main | sort) <(git diff --name-only $B HEAD | sort)   # sobreposição

• Branch nova nasce de origin/main deste repositório, com nome (fix/o-que-conserta), nunca do main do fork: o main do fork carrega as personalizações da instalação da pessoa (marca, .env, config) e um PR aberto dali propõe tudo isso ao produto inteiro — foi medido, sete arquivos com a marca de um cliente mergeando sem conflito (PR #465).
• Atraso > 0 → traga a main para dentro: git merge --ff-only origin/main se proprios=0, senão git merge origin/main. Nunca reset --hard nem push --force: apaga trabalho. Conflito se resolve lendo os dois lados (ver references/pre-voo.md, seção "conflito").
• Sobreposição (arquivos que a main também mudou) é onde nasce conflito: mescle cedo, não na hora do PR.
• O CI testa a branch, não o resultado do merge (strict=false na proteção da main): verde na branch atrasada não prova nada sobre o merge.

Passo 2 — arme os hooks (uma vez por clone)

bash .agents/skills/deskcomm-contribuir/scripts/armar-hooks.sh

Três guardas, e só isso: pre-commit reprova migration nova sem apêndice no baseline.sql e sem linha no MANIFEST.md no mesmo commit, e número (NNNN) ou timestamp já usado na origin/main ou em branch local; pre-push reprova push na main; e os dois avisam (sem bloquear) quando o commit está assinado como root@… ou sem e-mail — trabalho assinado assim não aparece no perfil do GitHub de quem fez. O mantenedor roda hooks próprios (loop/hooks); o script recusa sobrescrevê-los.

Passo 3 — antes de codar

• Leia a doutrina do que vai tocar: a skill deskcomm-doutrina aponta as três regras que mais custam (multi-tenancy com RLS, tripla de migration, nenhuma feature nomeia provider) e manda abrir o CLAUDE.md da origin/main — não de um resumo.
• Issue: comente "pego esta" antes de codar; um mantenedor atribui. Sem resposta em 48 h, comece e diga no PR. Issue com pessoa atribuída não se duplica.
• Peça de sistema (lead, agente, follow-up, tela, worker, métrica)? Carregue a skill sistema-vivo — o Living System Checklist é item do Definition of Done.

Passo 4 — o pré-voo, antes de abrir o PR

bash .agents/skills/deskcomm-contribuir/scripts/pre-voo.sh

Ele imprime, medido e com o comando ao lado, o que o mantenedor vai medir: atraso e sobreposição, arquivos fora do produto no diff (marca, .env, config do fork), segredo no diff, console.log novo (o lint só avisa), migration nova e a tripla, seção de versão escrita à mão no CHANGELOG.md (bloqueador — o corte de release é automático), fragmento em .changes/, documento de autoridade tocado, identidade dos commits. A leitura de cada item e o que fazer: references/pre-voo.md.

Depois, os gates que o CI roda sozinho — rode a suíte, não os gates que você lembra:

rm -f tsconfig*.tsbuildinfo; pnpm typecheck; echo exit=$?
pnpm lint; echo exit=$?
pnpm lint:channels; echo exit=$?
pnpm test:unit > /tmp/vt.log 2>&1; echo exit=$?; grep -aE "Test Files|Tests " /tmp/vt.log | tail -2
pnpm test:shell; echo exit=$?          # se tocou hostgator-setup-kit/, Dockerfile* ou compose
pnpm test:db; echo exit=$?             # se tocou schema/RLS/RBAC (precisa de Docker)
pnpm build; echo exit=$?

test:unit sem caminho: o script alcança o repositório inteiro (testes ao lado do código inclusive); vitest run tests/unit é um verde menor. Não corte a saída com tail — o rodapé é a autoridade e os nomes dos arquivos vermelhos são o único dado que permite reconciliar.

Passo 5 — o teste que falta, e a sabotagem

Mudou comportamento? Então existe um teste que fica vermelho sem a sua mudança. Se não existe, escreva. Depois commite e sabote: reverta só a linha do conserto (não o commit), preveja quantos casos vão cair (e quais), rode, confira a contagem, restaure. "1 vermelho de N, o previsto" vai no corpo do PR. Sabotar antes de commitar já custou trabalho perdido aqui mais de uma vez.

Passo 6 — prova em tela (se tocou UI ou fluxo de usuário)

A doutrina do repo: curl não prova experiência; Playwright dirigindo o front, num banco fresco do baseline.sql, com os envs opcionais ausentes (o estado real de uma instalação nova). A receita local inteira, na ordem, com o que precisa instalado: references/receita-e2e-local.md. Sem Docker ou sem tempo: mande o que conseguiu provar (unit + o que testou na mão, passo a passo) e diga que a prova de tela ficou com o mantenedor — é o combinado público, não uma falha.

Spec nova entra em SPECS_PARTE_N do .github/workflows/e2e.yml (ou em FORA_DO_CI com o motivo escrito); o teste tests/unit/e2e-cobertura-completa.test.ts reprova spec órfã.

Passo 7 — o fragmento de release (não o CHANGELOG)

Mudou algo que quem opera uma VPS percebe? Escreva .changes/<kebab>.md:

---
impacto: capacidade_nova        # nada_mudou | capacidade_nova | exige_acao
secao: adicionado               # adicionado | alterado | corrigido
titulo: O que muda, na voz de quem usa
---
Um parágrafo do ponto de vista do operador. Sem título, sem ⚠. Crédito: @seu-usuario.

pnpm release:conferir valida a forma. Nunca escreva ## [1.x.y] no CHANGELOG.md: o corte de release é automático e uma seção à mão já quase publicou uma versão pelo merge de um PR. exige_acao só se o operador precisa fazer algo na VPS (variável nova obrigatória, por exemplo) — e aí o instalador precisa perguntar por ela.

O texto do fragmento vira a nota pública da versão: a LP publica o CHANGELOG.md em deskcomm.com.br/changelog, nos três idiomas. Escreva para quem nunca viu o código.

Mexeu num guia (.agents/skills/deskcomm-*: nome, o que ele faz, como chamar)? Rode pnpm skills:sync e avise no PR que a página de guias da LP (deskcomm.com.br/guias, arquivo conteudo/guias.ts do repositório deskcomm-site) precisa acompanhar — senão ela passa a ensinar um guia que não existe.

As duas páginas saem de um PR do deskcomm-site; um 404 nesses dois links quer dizer que ele ainda não entrou, não que você errou o caminho.

Passo 8 — o PR

• Título no imperativo, do ponto de vista de quem usa (fix(agenda): a consulta remarcada não some do dia), commits em conventional commits, PT-BR aceito.
• Corpo: o que muda para quem usa; Closes #N; o que você mediu (comandos e saídas: o rodapé do test:unit, a sabotagem, a prova de tela); e um bloco "O que NÃO medi" — é o campo que separa medição de relato.
• Identidade: git log --format='%an <%ae>' origin/main..HEAD | sort -u — se aparecer root@… ou um e-mail que não é da sua conta, o trabalho não aparece no seu perfil. Conserte antes do push (git config user.email, git commit --amend --reset-author nos seus commits). É também a identidade que a triagem põe como autor quando porta o seu trabalho do lado de cá.
• Edição por mantenedores: com "Allow edits by maintainers" ligado (confira com gh pr view <n> --json maintainerCanModify --jq .maintainerCanModify), a triagem pode empurrar na sua branch um conserto ou o merge da main, avisando no PR antes. Antes de empurrar de novo, git pull --no-rebase — nunca --force.

O que vai parecer erro depois de abrir — e não é — e como acompanhar o CI de verdade: references/depois-do-pr.md. Os erros mais frequentes de quem contribui, com o número do PR onde aconteceram: references/erros-recorrentes.md.

O que você nunca faz

• git reset --hard, push --force, rebase de commits já publicados, stash pop em worktree que não é seu (o stash é compartilhado entre worktrees e importa trabalho alheio).
• Editar migration já aplicada — corrija com uma nova (forward-fix) e mais um apêndice.
• Tocar em worktree com árvore suja que não é sua.
• Trocar constante de marca, título de tela ou .env do produto para "a sua instalação" — isso vive no banco e na tela Configurações › Marca; no PR é vazamento.
• Fechar o próprio PR por achar que "fez ruído". Três pessoas fizeram isso sem ter errado nada.